CGpImage Class

CGpImageis an abstract base class that provides functionality for the CGpBitmap and CGpMetafile descended classes.

CGpImage provides methods for loading and saving raster images (bitmaps) and vector images (metafiles). An Image object encapsulates a bitmap or a metafile and stores attributes that you can retrieve by calling various methods. You can construct Image objects from a variety of file types including BMP, ICON, GIF, JPEG, Exif, PNG, TIFF, WMF, and EMF.

While it can be used directly, it is not recommended for most scenarios because it lacks essential functionality like resolution control, pixel access, and image effects. Use CGpBitmap for regular image files (e.g., JPEG, PNG, BMP, TIFF) and CGpMetafile for vector-based images (e.g., EMF, WMF).

DPI Awareness: When working with raster images, predictable rendering size depends on correctly setting the image’s resolution. The SetResolution method, available only in CGpBitmap, allows you to define the horizontal and vertical DPI (dots per inch) of the image. Without explicitly setting the resolution, GDI+ assumes a default of 96 DPI, which can lead to incorrect scaling on high-DPI displays. This means the image may appear smaller or larger than intended depending on its internal DPI metadata. To ensure consistent and accurate rendering across different screen resolutions and printing contexts, it is essential to use CGpBitmap instead of CGpImage and call SetResolution or SetResolutionForDpi after loading the image. If the image is a metafile we don’t need to call SetResolution. Metafiles (EMF, WMF) are vector-based, meaning they store drawing commands rather than pixel data. Their rendering is resolution-independent — they scale smoothly across devices and DPI settings without distortion. GDI+ uses logical units (like points or inches) to interpret metafile dimensions, so embedded DPI doesn’t affect their size or clarity.

Inherits from: CGpBase.
Include file: CGpBitmap.inc.

CGpBitmap Class

The CGpBitmap class inherits from the CGpImage class. It encapsulates a GDI+ bitmap, which consists of the pixel data for a graphics image and its attributes. A Bitmap is an object used to work with images defined by pixel data. There are many standard formats for saving a bitmap to a file. GDI+ supports the following file formats: BMP, GIF, EXIF, JPG, PNG, and TIFF.

You can create images from files, streams, and other sources by using one of the Bitmap constructors and save them to a stream or to the file system with the Save method. Images are drawn to the screen or to memory by using the DrawImage method of the Graphics object.

Inherits from: CGpImage.
Include file: CGpBitmap.inc.

CGpMetafile Class

Extends the CGpImage class. The Metafile object defines a graphic metafile. A metafile contains records that describe a sequence of graphics API calls. Metafiles can be recorded (constructed) and played back (displayed).

Inherits from: CGpImage.
Include file: CGpBitmap.inc.

CGpCachedBitmap Class

Creates a CachedBitmap object based on a Bitmap object and a Graphics object. The cached bitmap takes the pixel data from the Bitmap object and stores it in a format that is optimized for the display device associated with the Graphics object.

Inherits from: CGpBase.
Include file: CGpBitmap.inc.

CGpImageAttributes Class

Creates an ImageAttributes object that contains information about how bitmap and metafile colors are manipulated during rendering. An ImageAttributes object maintains several color-adjustment settings, including color-adjustment matrices, grayscale-adjustment matrices, gamma-correction values, color-map tables, and color-threshold values.

Inherits from: CGpBase.
Include file: CGpImageAttributes.inc.

Constructors (CGpImage)

CONSTRUCTOR CGpImage (BYVAL pImage AS CGpImage PTR)
CONSTRUCTOR CGpImage (BYVAL pwszFileName AS WSTRING PTR,  BYVAL useicm AS BOOLEAN = FALSE)
CONSTRUCTOR CGpImage (BYVAL pStream AS IStream PTR, BYVAL useicm AS BOOLEAN = FALSE)
CONSTRUCTOR CGpImage (BYVAL hInst AS HINSTANCE, BYREF wszImageName AS WSTRING)

Creates an Image object from another Image object.

CONSTRUCTOR CGpImage (BYVAL pImage AS CGpImage PTR)

Creates an Image object based on a file.

CONSTRUCTOR CGpImage (BYVAL pwszFileName AS WSTRING PTR,  BYVAL useicm AS BOOLEAN = FALSE)

Create a Image object based on an IStream interface.

CONSTRUCTOR CGpImage (BYVAL pStream AS IStream PTR, BYVAL useicm AS BOOLEAN = FALSE)

CONSTRUCTOR CGpImage (BYVAL hInst AS HINSTANCE, BYREF wszImageName AS WSTRING)

Example

This example is not DPI aware. Therefore, unless it is run virtualized, the coordinates won’t be scaled, and the image will be displayed smaller or bigger if its resolution is not 96.

' ========================================================================================
' The following example creates an Image object based on a JPEG file. Then the code calls
' the DrawImage method to draw the image.
' ========================================================================================
SUB Example_Constructor (BYVAL hdc AS HDC)

   ' // Create a graphics object from the window device context
   DIM graphics AS CGpGraphics = hdc

   ' // Create an Image object, and then clone it.
   DIM image AS CGpImage = "climber.jpg"

   ' // Draw the original image and the cloned image.
   graphics.DrawImage(@image, 10, 10)

END SUB
' ========================================================================================

This version is DPI aware. The coordinates will be scaled and the image will be displayed with the same relative size regardless of the DPI of the image. As the SetResolution and SetResolutionForDpi methods aren’t available in the CGpImage class, we must use the CGpBitmap class.

Tip: Always normalize image resolution when displaying multiple images. It’s the only way to guarantee consistent rendering size and layout across devices and formats.

' ========================================================================================
' The following example creates an Image object based on a JPEG file. Then the code calls
' the DrawImage method to draw the image.
' ========================================================================================
SUB Example_Constructor_HDPI (BYVAL hdc AS HDC)

   ' // Create a graphics object from the window device context
   DIM graphics AS CGpGraphics = hdc
   ' // Set the scaling factors using the DPI ratios
   graphics.ScaleTransformForDpi

   ' // Create an Image object
   DIM image AS CGpBitmap = "climber.jpg"
   ' // Set the resolution of the image using the DPI ratios od the device
   image.SetResolutionForDpi

   ' // Draw the original image and the cloned image.
   graphics.DrawImage(@image, 10, 10)

END SUB
' ========================================================================================

Clone (CGpImage)

Copies the contents of the existing Image object into a new Image object.

FUNCTION Clone (BYVAL pCloneImage AS CGpImage PTR) AS GpStatus

Example

' ========================================================================================
' The following example creates an Image object based on a JPEG file. The code creates a
' second Image object by cloning the first. Then the code calls the DrawImage method twice
' to draw the two images.
' ========================================================================================
SUB Example_Clone (BYVAL hdc AS HDC)

   ' // Create a graphics object from the window device context
   DIM graphics AS CGpGraphics = hdc
   ' // Get the DPI scaling ratio
   DIM rxRatio AS SINGLE = graphics.GetDpiX / 96
   DIM ryRatio AS SINGLE = graphics.GetDpiY / 96

   ' // Create an Image object, and then clone it.
   DIM image1 AS CGpImage = "climber.jpg"
   DIM pImage2 AS CGpImage
   image1.Clone(@pImage2)
   ' // You can also use:
   ' DIM pImage2 AS CGpImage = @image1

   ' // Draw the original image and the cloned image.
   graphics.DrawImage(@image1, 20 * rxRatio, 20 * ryRatio)
   graphics.DrawImage(@pImage2, 230 * rxRatio, 20 * ryRatio)

END SUB
' ========================================================================================

Example

This DPI aware version uses the CGpBitmap class to create the Image object and to clone it. Using the CGpBitmap class is needed to be able to use the SetResolution method.

SUB Example_Clone (BYVAL hdc AS HDC)

   ' // Create a graphics object from the window device context
   DIM graphics AS CGpGraphics = hdc
   ' // Set the scaling factors using the DPI ratios
   graphics.ScaleTransformForDpi

   ' // Create an Image object, and then clone it.
   DIM image1 AS CGpBitmap = "climber.jpg"
   image1.SetResolutionForDpi
   DIM image2 AS CGpBitmap = @image1

   ' // Draw the original image and the cloned image.
   graphics.DrawImage(@image1, 10, 10)
   graphics.DrawImage(@image2, 200, 10)

END SUB

FindFirstItem (CGpImage)

Retrieves the description and the data size of the first metadata item in an Image object.

FUNCTION FindFirstItem (BYVAL pitem AS ImageItemData PTR) AS GpStatus

Return value

If the function succeeds, it returns StatusOk, which is an element of the GpStatus enumeration.

If the function fails, it returns one of the other elements of the GpStatus enumeration.

Remarks

Use FindFirstItem along with FindNextItem to enumerate the metadata items, including custom metadata, stored in an image. FindFirstItem and FindNextItem do not enumerate the metadata items stored by the SetPropertyItem method.

FindNextItem (CGpImage)

The FindNextItem method is used along with the FindFirstItem method to enumerate the metadata items stored in an Image object. The FindNextItem method retrieves the description and the data size of the next metadata item in an Image object.

FUNCTION FindNextItem (BYVAL pitem AS ImageItemData PTR) AS GpStatus

Return value

If the function succeeds, it returns StatusOk, which is an element of the GpStatus enumeration.

If the function fails, it returns one of the other elements of the GpStatus enumeration.

Remarks

FindFirstItem and FindNextItem do not enumerate the metadata items stored by the SetPropertyItem method.

GetAllPropertyItems (CGpImage)

Gets all the property items (metadata) stored in an Image object.

FUNCTION GetAllPropertyItems (BYVAL totalBufferSize AS UINT, BYVAL numProperties AS UINT, _
   BYVAL allItems AS PropertyItem PTR) AS GpStatus

Return value

If the function succeeds, it returns StatusOk, which is an element of the GpStatus enumeration.

If the function fails, it returns one of the other elements of the GpStatus enumeration.

Remarks

Some image files contain metadata that you can read to determine features of the image. For example, a digital photograph might contain metadata that you can read to determine the make and model of the camera used to capture the image.

GDI+ stores an individual piece of metadata in a PropertyItem object. The GetAllPropertyItems method returns an array of PropertyItem objects. Before you call GetAllPropertyItems, you must allocate a buffer large enough to receive that array. You can call the GetPropertySize method of an Image object to get the size, in bytes, of the required buffer. The GetPropertySize method also gives you the number of properties (pieces of metadata) in the image.

Several enumerations and constants related to image metadata are defined in Gdiplusimaging.inc.

Example

'#CONSOLE ON
#define _WIN32_WINNT &h0602
#INCLUDE ONCE "AfxNova/CGdiPlus.inc"
USING AfxNova

' ========================================================================================
' The following example creates an Image object based on a JPEG file. The code calls the
' GdipGetAllPropertyItems function to obtain its property items (metadata).
' ========================================================================================

DIM hStatus AS LONG

' // Create a Bitmap object from a JPEG file.
DIM image AS CGpImage = "climber.jpg"

' // Get total buffer size and number of properties
DIM totalSize AS UINT, numProps AS UINT, buffer AS UBYTE PTR
hStatus = image.GetPropertySize(@totalSize, @numProps)
IF hStatus = 0 THEN
   ' // Allocate buffer and retrieve all property items
   buffer = Allocate(totalSize)
   hStatus = image.GetAllPropertyItems(totalSize, numProps, cast(PropertyItem PTR, buffer))
   IF hStatus = 0 THEN
      DIM propItem AS PropertyItem PTR
      FOR i AS LONG = 0 TO numProps - 1
         propItem = cast(PropertyItem PTR, buffer + i * SIZEOF(PropertyItem))
         PRINT "Property ID: &h"; HEX(propItem->id)
         PRINT "Type: "; propItem->type; " Length: "; propItem->length
         SELECT CASE propItem->type
            CASE PropertyTagTypeASCII
               PRINT "Value: "; *cast(ZSTRING PTR, propItem->value)
            CASE PropertyTagTypeByte
               DIM b AS UBYTE PTR = Cast(UBYTE PTR, propItem->value)
               FOR j AS LONG = 0 TO propItem->length - 1
                  PRINT b[j]; " ";
               NEXT
               PRINT
            CASE PropertyTagTypeShort
               DIM s AS USHORT PTR = cast(USHORT PTR, propItem->value)
                  FOR j AS LONG = 0 TO propItem->length \ 2 - 1
                     PRINT s[j]; " ";
                  NEXT
                  PRINT
            CASE PropertyTagTypeLong
               DIM l AS ULONG PTR = cast(ULONG PTR, propItem->value)
               FOR j AS LONG = 0 TO propItem->length \ 4 - 1
                  PRINT l[j]; " ";
               NEXT
               PRINT
            CASE ELSE
               PRINT "Unsupported type"
         END SELECT
         PRINT "---------------------------"
      NEXT
   ELSE
      PRINT "Failed to retrieve property items"
   END IF
END IF

' // Cleanup
IF buffer THEN Deallocate(buffer)

PRINT
PRINT "Press any key"
SLEEP

GetBounds (CGpImage)

Gets the bounding rectangle for the image.

FUNCTION GetBounds (BYVAL srcRect AS GpRectF PTR, BYVAL srcUnit AS GpUnit PTR) AS GpStatus

Return value

If the function succeeds, it returns StatusOk, which is an element of the GpStatus enumeration.

If the function fails, it returns one of the other elements of the GpStatus enumeration.

Remarks

The bounding rectangle for a metafile does not necessarily have (0, 0) as its upper-left corner. The coordinates of the upper-left corner can be negative or positive, depending on the drawing commands that were issued during the recording of the metafile. For example, suppose a metafile consists of a single ellipse that was recorded with the following statement:

DrawEllipse(pen, 200, 100, 80, 40)

Then the bounding rectangle for the metafile will enclose that one ellipse. The upper-left corner of the bounding rectangle will not be (0, 0); rather, it will be a point near (200, 100).

Example

' ========================================================================================
' The following example creates an Image object based on a file and then draws the image.
' Next, the code calls the Image.GetBounds method to get the bounding rectangle for the image
' and redraws a 75 per cent of the image.
' ========================================================================================
SUB Example_GetBounds (BYVAL hdc AS HDC)

   ' // Create a graphics object from the window device context
   DIM graphics AS CGpGraphics = hdc
   ' // Set the scaling factors using the DPI ratios
   graphics.ScaleTransformForDpi

   DIM image AS CGpBitmap = "climber.jpg"
   image.SetResolutionForDpi
   graphics.DrawImage(@image, 10, 10)

   ' // Get the bounding rectangle for the image
   DIM rcf AS GpRectF, unit AS GpUnit
   image.GetBounds(@rcf, @unit)

   ' // Draw 75 percent of the image.
   graphics.DrawImage(@image, 200, 10, rcf.X, rcf.Y, 0.75 * rcf.Width, rcf.Height, unit)

END SUB
' ========================================================================================

Example

' ========================================================================================
' The following example creates an Image object based on a metafile and then draws the image.
' Next, the code calls the Image.GetBounds method to get the bounding rectangle for the image
' and redraws a 75 per cent of the image.
' ========================================================================================
SUB Example_GetBounds (BYVAL hdc AS HDC)

   ' // Create a graphics object from the window device context
   DIM graphics AS CGpGraphics = hdc
   ' // Set the scaling factors using the DPI ratios
   graphics.ScaleTransformForDpi

   DIM image AS CGpBitmap = "SampleMetafile.emf"
   graphics.DrawImage(@image, 10, 10)

   ' // Get the bounding rectangle for the image
   DIM rcf AS GpRectF, unit AS GpUnit
   image.GetBounds(@rcf, @unit)

   ' // Draw 75 percent of the image.
   graphics.DrawImage(@image, 200, 10, rcf.X, rcf.Y, 0.75 * rcf.Width, rcf.Height, unit)

END SUB
' ========================================================================================

GetEncoderParameterList (CGpImage)

Gets a list of the parameters supported by a specified image encoder.

FUNCTION GetEncoderParameterList (BYVAL clsidEncoder AS GUID PTR, BYVAL uSize AS UINT, _
   BYVAL buffer AS EncoderParameters PTR) AS GpStatus

Return value

If the function succeeds, it returns StatusOk, which is an element of the GpStatus enumeration.

If the function fails, it returns one of the other elements of the GpStatus enumeration.

Remarks

The GetEncoderParameterList method returns an array of EncoderParameter objects. Before you call GetEncoderParameterList, you must allocate a buffer large enough to receive that array, which is part of an EncoderParameters object. You can call the GetEncoderParameterListSize method to get the size, in bytes, of the required EncoderParameters object.

GetEncoderParameterListSize (CGpImage)

Gets the size, in bytes, of the parameter list for a specified image encoder.

FUNCTION GetEncoderParameterListSize (BYVAL clsidEncoder AS GUID PTR) AS UINT

GetFlags (CGpImage)

Gets a set of flags that indicate certain attributes of an Image object.

FUNCTION GetFlags () AS UINT

Return value

This method returns a value that holds a set of single-bit flags. The flags are defined in the ImageFlags enumeration.

ImageFlags enumeration

For example, if the GetFlags property for an image returned 77960, the ImageFlags for the image would be ReadOnly, HasRealDpi, HasRealPixelSize, ColorSpaceYcbcr, and PartiallyScalable.

Example

'#CONSOLE ON
#define _WIN32_WINNT &h0602
#INCLUDE ONCE "AfxNova/CGdiPlus.inc"
USING AfxNova

' ========================================================================================
' The following example retrieves the flags of an image.
' ========================================================================================

' // Create a Bitmap object from a JPEG file.
DIM image AS CGpImage = "climber.jpg"

' // Get the image flags
DIM flags AS UINT = image.GetFlags
PRINT "Image flags &h" & HEX(flags)

' // Interpret the flags
IF (flags AND ImageFlagsHasAlpha) THEN PRINT "Has Alpha Channel"
IF (flags AND ImageFlagsHasRealDPI) THEN PRINT "Has real DPI"
' ... etc.

PRINT
PRINT "Press any key"
SLEEP

GetFrameCount (CGpImage)

Gets the number of frames in a specified dimension of an Image object.

FUNCTION GetFrameCount (BYVAL dimensionID AS GUID PTR) AS UINT

Example

'#CONSOLE ON
#define _WIN32_WINNT &h0602
#INCLUDE ONCE "AfxNova/CGdiPlus.inc"
#INCLUDE ONCE "AfxNova/AfxCOM.inc"
USING AfxNova

' ========================================================================================
' Gets the number of frames in a specified dimension of an Image object.
' ========================================================================================

' // Create a Bitmap object from a JPEG file.
DIM image AS CGpImage = "MultiFrame.tiff"

' // How many frame dimensions does the Image object have?
DIM nCount AS UINT = image.GetFrameDimensionsCount
PRINT "The number of dimensions is " & STR(nCount)

' // Get the list of frame dimensions from the Image object.
DIM rgDimensionIDs(nCount - 1) AS GUID
image.GetFrameDimensionsList(@rgDimensionIDs(0), nCount)

' // Display the GUID of the first (and only) frame dimension.
DIM strGuid AS STRING = AfxGuidText(rgDimensionIDs(0))
'   strGuid = AfxGuidText(rgDimensionIDs(0))
PRINT "The first (and only) dimension ID is " & strGuid

' // Get the number of frames in the first dimension.
DIM frameCount AS UINT = image.GetFrameCount(@rgDimensionIDs(0))
PRINT "The number of frames in that dimension is " & STR(frameCount)

PRINT
PRINT "Press any key"
SLEEP

GetFrameDimensionsCount (CGpImage)

Gets the number of frame dimensions in an Image object.

FUNCTION GetFrameDimensionsCount () AS UINT

Remarks

This method returns information about multiple-frame images, which come in two styles: multiple page and multiple resolution.

A multiple-page image is an image that contains more than one image. Each page contains a single image (or frame). These pages (or images, or frames) are typically displayed in succession to produce an animated sequence, such as in an animated GIF file.

A multiple-resolution image is an image that contains more than one copy of an image at different resolutions.

Windows GDI+ can support an arbitrary number of pages (or images, or frames), as well as an arbitrary number of resolutions.

Example

'#CONSOLE ON
#define _WIN32_WINNT &h0602
#INCLUDE ONCE "AfxNova/CGdiPlus.inc"
#INCLUDE ONCE "AfxNova/AfxCOM.inc"
USING AfxNova

' ========================================================================================
' Gets the number of frame dimensions in the image object and the identifier of the frame.
' ========================================================================================

' // Create a Bitmap object from a JPEG file.
DIM image AS CGpImage = "MultiFrame.tiff"

' // How many frame dimensions does the Image object have?
DIM nCount AS UINT = image.GetFrameDimensionsCount
PRINT "The number of dimensions is " & STR(nCount)

' // Get the list of frame dimensions from the Image object.
DIM rgDimensionIDs(nCount - 1) AS GUID
image.GetFrameDimensionsList(@rgDimensionIDs(0), nCount)

' // Display the GUID of the first (and only) frame dimension.
DIM strGuid AS STRING = AfxGuidText(rgDimensionIDs(0))
'   strGuid = AfxGuidText(rgDimensionIDs(0))
PRINT "The first (and only) dimension ID is " & strGuid

' // Get the number of frames in the first dimension.
DIM frameCount AS UINT = image.GetFrameCount(@rgDimensionIDs(0))
PRINT "The number of frames in that dimension is " & STR(frameCount)

PRINT
PRINT "Press any key"
SLEEP

GetFrameDimensionsList (CGpImage)

Gets the identifiers for the frame dimensions of an Image object.

FUNCTION GetFrameDimensionsList (BYVAL dimensionIDs AS GUID PTR, BYVAL count AS UINT) AS GpStatus

Return value

If the function succeeds, it returns StatusOk, which is an element of the GpStatus enumeration.

If the function fails, it returns one of the other elements of the GpStatus enumeration.

Remarks

This method returns information about multiple-frame images, which come in two styles: multiple page and multiple resolution.

A multiple-page image is an image that contains more than one image. Each page contains a single image (or frame). These pages (or images, or frames) are typically displayed in succession to produce an animated sequence, such as in an animated GIF file.

A multiple-resolution image is an image that contains more than one copy of an image at different resolutions. This is commonly used by MIP mapping where the displayed image size determines the resolution of the image used for drawing. GDI+ can support an arbitrary number of pages (or images, or frames), as well as an arbitrary number of resolutions.

Example

'#CONSOLE ON
#define _WIN32_WINNT &h0602
#INCLUDE ONCE "AfxNova/CGdiPlus.inc"
#INCLUDE ONCE "AfxNova/AfxCOM.inc"
USING AfxNova

' ========================================================================================
' Get the list of frame dimensions from the Image object.
' ========================================================================================

' // Create a Bitmap object from a JPEG file.
DIM image AS CGpImage = "MultiFrame.tiff"

' // How many frame dimensions does the Image object have?
DIM nCount AS UINT = image.GetFrameDimensionsCount
PRINT "The number of dimensions is " & STR(nCount)

' // Get the list of frame dimensions from the Image object.
DIM rgDimensionIDs(nCount - 1) AS GUID
image.GetFrameDimensionsList(@rgDimensionIDs(0), nCount)

' // Display the GUID of the first (and only) frame dimension.
DIM strGuid AS STRING = AfxGuidText(rgDimensionIDs(0))
'   strGuid = AfxGuidText(rgDimensionIDs(0))
PRINT "The first (and only) dimension ID is " & strGuid

' // Get the number of frames in the first dimension.
DIM frameCount AS UINT = image.GetFrameCount(@rgDimensionIDs(0))
PRINT "The number of frames in that dimension is " & STR(frameCount)

PRINT
PRINT "Press any key"
SLEEP

GetHeight (CGpImage)

Gets the image height, in pixels, of an image.

FUNCTION GetHeight () AS UINT

Example

'#CONSOLE ON
#define _WIN32_WINNT &h0602
#INCLUDE ONCE "AfxNova/CGdiPlus.inc"
USING AfxNova

' ========================================================================================
' The following example retrieves the height of an image.
' ========================================================================================

' // Create a Bitmap object from a JPEG file.
DIM image AS CGpImage = "climber.jpg"

' // Get the height of the image
DIM nHeight AS UINT = image.GetHeight
PRINT "Image height: " & WSTR(nHeight)

PRINT
PRINT "Press any key"
SLEEP

GetHorizontalResolution (CGpImage)

Gets the horizontal resolution, in dots per inch, of an image.

FUNCTION GetHorizontalResolution () AS SINGLE

Example

' ========================================================================================
' The following example retrieves the horizontal resolution, in dots per inch, of an image.
' ========================================================================================

' // Create a Bitmap object from a JPEG file.
DIM image AS CGpImage = "climber.jpg"

' // Get the width of the image
DIM resolution AS SINGLE = image.GetHorizontalResolution
PRINT "The horizontal resolution is " & STR(resolution) & " dots per inch"

PRINT
PRINT "Press any key"
SLEEP

GetItemData (CGpImage)

Gets one piece of metadata from an Image object.

FUNCTION GetItemData (BYVAL pitem AS ImageItemData PTR) AS GpStatus

Return value

If the function succeeds, it returns StatusOk, which is an element of the GpStatus enumeration.

If the function fails, it returns one of the other elements of the GpStatus enumeration.

GetPalette (CGpImage)

Gets the ColorPalette of an Image object.

FUNCTION GetPalette (BYVAL pal AS ColorPalette PTR, BYVAL nSize AS INT_) AS GpStatus

Return value

If the function succeeds, it returns StatusOk, which is an element of the GpStatus enumeration.

If the function fails, it returns one of the other elements of the GpStatus enumeration.

Example

'#CONSOLE ON
#define _WIN32_WINNT &h0602
#INCLUDE ONCE "AfxNova/CGdiPlus.inc"
USING AfxNova

' ========================================================================================
' The following example creates an Image object based on a BMP file. The image in that file
' uses 8 bits per pixel. The code calls the GetPaletteSize method to determine the size of
' the image's palette. The call to Allocate allocates a buffer large enough to receive the
' palette, and the call to the GetPalette method fills that buffer. The code displays the
' number of colors in the palette and then displays the ARGB values of the first five colors
' in the palette.
' ========================================================================================

' // Create a Bitmap object from a JPEG file.
DIM image AS CGpImage = "climber8bit.bmp"

' // Get the size of the palette
DIM paletteSize AS LONG = image.GetPaletteSize
PRINT "The size of the palette is" & STR(paletteSize) & " bytes"

' // Allocate buffer
DIM _palette AS ColorPalette PTR
_palette = Allocate(paletteSize)

' // Retrieve the palette
image.GetPalette(_palette, paletteSize)

' Print first few entries
FOR i AS INTEGER = 0 TO MIN(5, _palette->Count - 1)
   DIM argb AS ARGB = _palette->Entries(i)
   PRINT "Color "; i; ": &h"; HEX(argb)
NEXT

PRINT
PRINT "Press any key"
SLEEP

GetPaletteSize (CGpImage)

Gets the size, in bytes, of the color palette of an Image object.

FUNCTION GetPaletteSize () AS INT_

Example

'#CONSOLE ON
#define _WIN32_WINNT &h0602
#INCLUDE ONCE "AfxNova/CGdiPlus.inc"
USING AfxNova

' ========================================================================================
' The following example creates an Image object based on a BMP file. The image in that file
' uses 8 bits per pixel. The code calls the GetPaletteSize method to determine the size of
' the image's palette. The call to Allocate allocates a buffer large enough to receive the
' palette, and the call to the GetPalette method fills that buffer. The code displays the
' number of colors in the palette and then displays the ARGB values of the first five colors
' in the palette.
' ========================================================================================

' // Create a Bitmap object from a JPEG file.
DIM image AS CGpImage = "climber8bit.bmp"

' // Get the size of the palette
DIM paletteSize AS LONG = image.GetPaletteSize
PRINT "The size of the palette is" & STR(paletteSize) & " bytes"

GetPhysicalDimension (CGpImage)

Gets the width and height of an Image object. If the image is a bitmap, the width and height are returned in pixels. If the image is a metafile, the width and height are returned in 0.01 millimeter units.

FUNCTION GetPhysicalDimension (BYVAL psize AS SizeF PTR) AS GpStatus

Return value

If the function succeeds, it returns StatusOk, which is an element of the GpStatus enumeration.

If the function fails, it returns one of the other elements of the GpStatus enumeration.

Example

'#CONSOLE ON
#define _WIN32_WINNT &h0602
#INCLUDE ONCE "AfxNova/CGdiPlus.inc"
USING AfxNova

' ========================================================================================
' The following example retrieves the width and height of an image.
' ========================================================================================

' // Create a Bitmap object from a JPEG file.
DIM image AS CGpImage = "climber.jpg"

' // Get the width and height of the image
DIM sizef AS GpSizeF = image.GetPhysicalDimension
PRINT "Image width: " & WSTR(sizef.Width)
PRINT "Image height: " & WSTR(sizef.Height)

PRINT
PRINT "Press any key"
SLEEP

GetPixelFormat (CGpImage)

Gets the pixel format of an Image object.

FUNCTION GetPixelFormat () AS PixelFormat

Return value

This method returns an integer that indicates the pixel format of an Image object. The PixelFormat data type and constants that represent various pixel formats are defined in Gdipluspixelformats.h.

Example

'#CONSOLE ON
#define _WIN32_WINNT &h0602
#INCLUDE ONCE "AfxNova/CGdiPlus.inc"
USING AfxNova

' ========================================================================================
' This example creates an Image object, gets the pixel format of the Image object and
' compares the obtained value to particular pixel format constants.
' ========================================================================================

' // Create a Bitmap object from a JPEG file.
DIM image AS CGpImage = "climber.jpg"

' // Get the pixel format
DIM fmt AS PixelFormat = image.GetPixelFormat

DIM strFormat AS STRING
SELECT CASE fmt
   CASE PixelFormat1bppIndexed    : strFormat = "1 bpp indexed"
   CASE PixelFormat4bppIndexed    : strFormat = "4 bpp indexed"
   CASE PixelFormat8bppIndexed    : strFormat = "8 bpp indexed"
   CASE PixelFormat16bppGrayScale : strFormat = "16 bpp gray scale"
   CASE PixelFormat16bppRGB555    : strFormat = "16 bpp RGB 555"
   CASE PixelFormat16bppRGB565    : strFormat = "16 bpp RGB 565"
   CASE PixelFormat16bppARGB1555  : strFormat = "16 bpp ARGB 1555"
   CASE PixelFormat24bppRGB       : strFormat = "24 bpp RGB"
   CASE PixelFormat32bppRGB       : strFormat = "32 bpp RGB"
   CASE PixelFormat32bppARGB      : strFormat = "32 bpp ARGB"
   CASE PixelFormat32bppPARGB     : strFormat = "32 bpp PARGB"
   CASE PixelFormat48bppRGB       : strFormat = "48 bpp RGB"
   CASE PixelFormat64bppARGB      : strFormat = "64 bpp ARGB"
   CASE PixelFormat64bppPARGB     : strFormat = "64 bpp PARGB"
   CASE ELSE
      strFormat = STR(fmt)
END SELECT

PRINT "The pixel format of the image is " & strFormat

PRINT
PRINT "Press any key"
SLEEP

GetPropertyCount (CGpImage)

Gets the number of properties (pieces of metadata) stored in an Image object.

FUNCTION GetPropertyCount () AS UINT

Example

'#CONSOLE ON
#define _WIN32_WINNT &h0602
#INCLUDE ONCE "AfxNova/CGdiPlus.inc"
USING AfxNova

' ========================================================================================
' The following example retrieves the property count of an image.
' ========================================================================================

' // Create a Bitmap object from a JPEG file.
DIM image AS CGpImage = "climber.jpg"

' // Get the property count
DIM count AS UINT = image.GetPropertyCount
PRINT "Property count: " & WSTR(count)

PRINT
PRINT "Press any key"
SLEEP

GetPropertyIdList (CGpImage)

Gets a list of the property identifiers used in the metadata of an Image object, one for each property item stored in the image.

FUNCTION GetPropertyIdList (BYVAL numOfProperties AS UINT, BYVAL list AS PROPID PTR) AS GpStatus

Return value

If the function succeeds, it returns StatusOk, which is an element of the GpStatus enumeration.

If the function fails, it returns one of the other elements of the GpStatus enumeration.

Remarks

The GetPropertyIdList method returns an array of PROPIDs. Before you call GetPropertyIdList, you must allocate a buffer large enough to receive that array. You can call the GetPropertyCount method of an Image object to determine the size of the required buffer. The size of the buffer should be the return value of GetPropertyCount multiplied by SIZEOF(PROPID).

Example

'#CONSOLE ON
#define _WIN32_WINNT &h0602
#INCLUDE ONCE "AfxNova/CGdiPlus.inc"
#INCLUDE ONCE "AfxNova/AfxCOM.inc"
USING AfxNova

' ========================================================================================
' Gets a list of the property identifiers used in the metadata of an Image object.
' ========================================================================================

' // Create a Bitmap object from a JPEG file.
DIM image AS CGpImage = "climber.jpg"

' // Get the pixel format
DIM rguid AS GUID = image.GetRawFormat
PRINT "Gud: " & AfxGuidText(rguid)

' // Get the number of properties
DIM count AS UINT = Image.GetPropertyCount
PRINT "Number of properties = " & STR(count)

' // Get the list of properties
DIM propIDs(count - 1) AS PROPID
image.GetPropertyIdList(count, @propIDs(0))
FOR i AS LONG = 0 TO count - 1
   PRINT "PROPID: &h" & HEX(propIDs(i))
NEXT

PRINT
PRINT "Press any key"
SLEEP

GetPropertyItem (CGpImage)

Gets a specified property item (piece of metadata) from an Image object.

FUNCTION GetPropertyItem (BYVAL propId AS PROPID, BYVAL propSize AS UINT, _
   BYVAL buffer AS PropertyItem PTR) AS GpStatus

Return value

If the function succeeds, it returns StatusOk, which is an element of the GpStatus enumeration.

If the function fails, it returns one of the other elements of the GpStatus enumeration.

Example

'#CONSOLE ON
#define _WIN32_WINNT &h0602
#INCLUDE ONCE "AfxNova/CGdiPlus.inc"
USING AfxNova

' ========================================================================================
' Gets a specified property item (piece of metadata) from an image.
' ========================================================================================

' // Create a Bitmap object from a JPEG file.
DIM image AS CGpImage = "climber.jpg"

' // Get the size of the specified property item.
DIM itemSize AS UINT = image.GetPropertyItemSize(PropertyTagLuminanceTable)

' // Allocate buffer and retrieve item
DIM buffer AS STRING = SPACE(itemSize)
DIM status AS LONG = image.GetPropertyItem(PropertyTagLuminanceTable, itemSize, cast(PropertyItem PTR, STRPTR(buffer)))
IF status = StatusOk Then
   DIM propItem AS PropertyItem PTR = cast(PropertyItem PTR, STRPTR(buffer))
   DIM values AS UBYTE PTR = cast(UBYTE PTR, propItem->value)
   PRINT "Luminance Table ("; propItem->length; " bytes):"
   FOR i AS LONG = 0 TO propItem->length - 1
      PRINT values[i]; " ";
      IF (i + 1) MOD 16 = 0 THEN PRINT
   NEXT
ELSE
   PRINT "Failed to retrieve luminance table"
END IF

PRINT
PRINT "Press any key"
SLEEP

GetPropertyItemSize (CGpImage)

Gets the size, in bytes, of a specified property item of an Image object.

FUNCTION GetPropertyItemSize (BYVAL propId AS PROPID) AS UINT

Example

'#CONSOLE ON
#define _WIN32_WINNT &h0602
#INCLUDE ONCE "AfxNova/CGdiPlus.inc"
USING AfxNova

' ========================================================================================
' Gets a specified property item (piece of metadata) from an image.
' ========================================================================================

' // Create a Bitmap object from a JPEG file.
DIM image AS CGpImage = "climber.jpg"

' // Get the size of the specified property item.
DIM itemSize AS UINT = image.GetPropertyItemSize(PropertyTagLuminanceTable)

GetPropertySize (CGpImage)

Gets the total size, in bytes, of all the property items stored in an Image object. The GetPropertySize method also gets the number of property items stored in an Image object.

FUNCTION GetPropertySize (BYVAL totalBufferSize AS UINT PTR, BYVAL numProperties AS UINT PTR) AS GpStatus

Return value

If the function succeeds, it returns StatusOk, which is an element of the GpStatus enumeration.

If the function fails, it returns one of the other elements of the GpStatus enumeration.

Remarks

Windows GDI+ stores an individual piece of metadata in a PropertyItem structure. The GetAllPropertyItems method returns an array of PropertyItem structures. Before you call GetAllPropertyItems, you must allocate a buffer large enough to receive that array. You can call the GetPropertySize method of an Image object to get the size, in bytes, of the required buffer. The GetPropertySize method also gives you the number of properties (pieces of metadata) in the image.

Example

'#CONSOLE ON
#define _WIN32_WINNT &h0602
#INCLUDE ONCE "AfxNova/AfxGdiPlus.inc"

' ========================================================================================
' Gets the total size, in bytes, of all the property items stored in an Image object.
' It also gets the number of property items stored in the Image object.
' ========================================================================================

DIM hStatus AS LONG

' // Initialize GDI+
DIM token AS ULONG_PTR = AfxGdipInit

' // Load the original image from file
DIM image AS GpImage PTR
hStatus = GdipLoadImageFromFile("BERRY_Halle_01.jpg", @image)

DIM AS UINT totalBufferSize, numProperties
hStatus = GdipGetPropertySize(image, @totalBufferSize, @numProperties)
IF hStatus = StatusOK THEN
   print "Total buffer size: " & WSTR(totalBufferSize)
   print "Number of properties: " & WSTR(numProperties)
END IF

' // Cleanup
IF image THEN GdipDisposeImage(image)

' // Shutdown GDI+
AfxGdipShutdown token

PRINT
PRINT "Press any key"
SLEEP

GetRawFormat (CGpImage)

Gets a globally unique identifier ( GUID) that identifies the format of an Image object.

FUNCTION GetRawFormat (BYVAL guidformat AS GUID PTR) AS GpStatus

Return value

If the function succeeds, it returns StatusOk, which is an element of the GpStatus enumeration.

If the function fails, it returns one of the other elements of the GpStatus enumeration.

Example

'#CONSOLE ON
#define _WIN32_WINNT &h0602
#INCLUDE ONCE "AfxNova/CGdiPlus.inc"
#INCLUDE ONCE "AfxNova/AfxCOM.inc"
USING AfxNova

' ========================================================================================
' Gets a list of the property identifiers used in the metadata of an Image object.
' ========================================================================================

' // Create a Bitmap object from a JPEG file.
DIM image AS CGpImage = "climber.jpg"

' // Get the pixel format
DIM rguid AS GUID = image.GetRawFormat
PRINT "Gud: " & AfxGuidText(rguid)

' // Get the number of properties
DIM count AS UINT = Image.GetPropertyCount
PRINT "Number of properties = " & STR(count)

' // Get the list of properties
DIM propIDs(count - 1) AS PROPID
image.GetPropertyIdList(count, @propIDs(0))
FOR i AS LONG = 0 TO count - 1
   PRINT "PROPID: &h" & HEX(propIDs(i))
NEXT

PRINT
PRINT "Press any key"
SLEEP

GetThumbnailImage (CGpImage)

Gets a thumbnail image from an Image object.

FUNCTION GetThumbnailImage (BYVAL thumbWidth AS UINT, BYVAL thumbHeight AS UINT, _
   BYVAL pThumbnail AS CGpImage PTR, BYVAL pCallback AS ANY PTR = NULL, _
   BYVAL callbackData AS ANY PTR = NULL) AS GpStatus

Return value

If the function succeeds, it returns StatusOk, which is an element of the GpStatus enumeration.

If the function fails, it returns one of the other elements of the GpStatus enumeration.

Remarks

A thumbnail image is a small copy of an image. Some image files have a thumbnail image embedded in the file. In such cases, this method retrieves the embedded thumbnail image. If there is no embedded thumbnail image, this method creates a thumbnail image by scaling the main image to the size specified in the thumbWidth and thumbHeight parameters. If both of those parameters are 0, a system-defined size is used.

Example

' ========================================================================================
' The following example creates a Bitmap object based on a JPEG file. The code calls the
' Bitmao.GetThumbnailImage method of that Bitmap object and then displays the thumbnail image
' along with the main image.
' ========================================================================================
SUB Example_GetThumbnailImage (BYVAL hdc AS HDC)

   ' // Create a graphics object from the window device context
   DIM graphics AS CGpGraphics = hdc
   ' // Set the scaling factors using the DPI ratios
   graphics.ScaleTransformForDpi

   ' // Create a Bitmap object from a JPEG file.
   DIM bmp AS CGpBitmap = "climber.jpg"
   ' // Set the resolution of the image using the DPI ratios
   bmp.SetResolutionForDpi

   ' // Get a thumbnail of the image of the specified width and height
   DIM thumbnail AS CGpBitmap
   bmp.GetThumbnailImage(70, 50, @thumbnail)

   ' // Draw the original image
   graphics.DrawImage(@bmp, 10, 10)
   ' // Draw the thumbnail image
   graphics.DrawImage(@thumbnail, 220, 10)

END SUB
' ========================================================================================

GetType (CGpImage)

Gets the type (bitmap or metafile) of an Image object.

FUNCTION GetType () AS ImageType

Return value

This method returns an element of the ImageType enumeration that indicates the image type.

Example

'#CONSOLE ON
#define _WIN32_WINNT &h0602
#INCLUDE ONCE "AfxNova/CGdiPlus.inc"
USING AfxNova

' ========================================================================================
' The following example gets the type (bitmap or metafile) of an Image object.
' ========================================================================================

' // Create a Bitmap object from a JPEG file.
DIM image AS CGpImage = "climber.jpg"

' // Get the type of the image
DIM imageType AS LONG = image.GetType
IF imageType = ImageTypeBitmap THEN PRINT "The type of image is ImageTypeBitmap"

PRINT
PRINT "Press any key"
SLEEP

GetVerticalResolution (CGpImage)

Gets the vertical resolution, in dots per inch, of the image.

FUNCTION GetVerticalResolution () AS SINGLE

Example

'#CONSOLE ON
#define _WIN32_WINNT &h0602
#INCLUDE ONCE "AfxNova/CGdiPlus.inc"
USING AfxNova

' ========================================================================================
' The following example retrieves the the vertical resolution, in dots per inch, of an image.
' ========================================================================================

' // Create a Bitmap object from a JPEG file.
DIM image AS CGpImage = "climber.jpg"

' // Get the vertical resolution of the image
DIM resolution AS SINGLE = image.GetVerticalResolution
PRINT "The vertical resolution is " & STR(resolution) & " dots per inch"

PRINT
PRINT "Press any key"
SLEEP

GetWidth (CGpImage)

Gets the width, in pixels, of the image.

FUNCTION GetWidth () AS UINT

Example

'#CONSOLE ON
#define _WIN32_WINNT &h0602
#INCLUDE ONCE "AfxNova/CGdiPlus.inc"
USING AfxNova

' ========================================================================================
' The following example retrieves the width of an image.
' ========================================================================================

' // Create a Bitmap object from a JPEG file.
DIM image AS CGpImage = "climber.jpg"

' // Get the width of the image
DIM nWidth AS UINT = image.GetWidth
PRINT "Image width: " & WSTR(nWidth)

PRINT
PRINT "Press any key"
SLEEP

RemovePropertyItem (CGpImage)

Removes a property item (piece of metadata) from an Image object.

FUNCTION RemovePropertyItem (BYVAL propId AS PROPID) AS GpStatus

Return value

If the function succeeds, it returns StatusOk, which is an element of the GpStatus enumeration.

If the function fails, it returns one of the other elements of the GpStatus enumeration.

Remarks

The RemovePropertyItem method removes a specified property from an Image object, but that property item is not removed from the file or stream that was used to construct the Image object. To save the image (with the property item removed) to a new JPEG file or stream, call the Save method of the Image object.

RotateFlip (CGpImage)

Rotates and flips an image.

FUNCTION RotateFlip (BYVAL rotateFlipType AS RotateFlipType) AS GpStatus

Return value

If the function succeeds, it returns StatusOk, which is an element of the GpStatus enumeration.

If the function fails, it returns one of the other elements of the GpStatus enumeration.

Example

' ========================================================================================
' The following example creates a Bitmap object based on a JPEG file. The code calls the
' RotateFlip method to rotate and flip the image 90 degrees.
' ========================================================================================
SUB Example_RotateFlip (BYVAL hdc AS HDC)

   ' // Create a graphics object from the window device context
   DIM graphics AS CGpGraphics = hdc
   ' // Set the scaling factors using the DPI ratios
   graphics.ScaleTransformForDpi

   ' // Create a Bitmap object from a JPEG file.
   DIM image AS CGpBitmap = "climber.jpg"
   ' // Set the resolution of the image using the DPI ratios
   image.SetResolutionForDpi
   ' // Draw the bitmap
   graphics.DrawImage(@image, 10, 10)

   ' // Rotate and flip the birmap 90 degrees
   image.RotateFlip(Rotate90FlipY)
   ' // Draw the rotated bitmap
   graphics.DrawImage(@image, 220, 10)

END SUB
' ========================================================================================

Because metafiles are a list of drawing commands, not a raster representation, RotateFlip can’t be used with them. A simulation can be doneusing the TranslateTransform and RotateTransform methods.

' ========================================================================================
' The following example creates an Image object based on a metafile. The code calls the
' TranslateTransform and RotateTransform methods to rotate and flip the image 90 degrees.
' ========================================================================================
SUB Example_RotateFlipMetafile (BYVAL hdc AS HDC)

   ' // Create a graphics object from the window device context
   DIM graphics AS CGpGraphics = hdc
   ' // Set the scaling factors using the DPI ratios
   graphics.ScaleTransformForDpi

   ' // Create a Metafile object from file.
   DIM image AS CGpBitmap = "SampleMetafile.emf"

   ' // Translate to rotation origin
   graphics.TranslateTransform(250, 10) ' Adjust as needed

   ' // Rotate 90 degrees clockwise
   graphics.RotateTransform(90)

   graphics.DrawImage(@image, 0, 0)

END SUB
' ========================================================================================

Save (CGpImage)

Saves the image to a file.

FUNCTION Save (BYVAL pwszFileName AS WSTRING PTR, BYVAL clsidEncoder AS GUID PTR, _
   BYVAL encoderParams AS EncoderParameters PTR) AS GpStatus
FUNCTION Save (BYVAL pStream AS IStream PTR, BYVAL clsidEncoder AS GUID PTR, _
   BYVAL encoderParams AS EncoderParameters PTR) AS GpStatus

Return value

If the function succeeds, it returns StatusOk, which is an element of the GpStatus enumeration.

If the function fails, it returns one of the other elements of the GpStatus enumeration.

Remarks

GDI+ does not allow you to save an image to the same file that you used to construct the image. The following code creates an Image object by passing the file name MyImage.jpg to an Image constructor. That same file name is passed to the Save method of the Image object, so the Save method fails.

Example

'#CONSOLE ON
#define _WIN32_WINNT &h0602
#INCLUDE ONCE "AfxNova/CGdiPlus.inc"
USING AfxNova

' ========================================================================================
' The following code saves a file to disk.
' ========================================================================================

' // Create a Bitmap object from a JPEG file.
DIM image AS CGpImage = "climber.jpg"

' // Get the encoder GUID for the .png image type
DIM clsidEncoder AS GUID = AfxGdipGetEncoderClsid("image/png")

' // Save the file with another name and format
IF image.Save("saved.png", @clsidEncoder, NULL) = StatusOk THEN
   PRINT "File saved"
ELSE
   PRINT "Failed to save the file"
END IF

PRINT
PRINT "Press any key"
SLEEP

Example

'#CONSOLE ON
#define _WIN32_WINNT &h0602
#INCLUDE ONCE "AfxNova/CGdiPlus.inc"
USING AfxNova

' ========================================================================================
' The following example retrieves the width of an image.
' ========================================================================================

' // Create two image objects.
DIM image1 AS CGpImage = "Iron.jpg"
DIM image2 AS CGpImage = "House.jpg"

' // Create compound file
DIM storage AS IStorage PTR
DIM compoundFileName AS WSTRING * 260 = "CompoundFile.cmp"
StgCreateDocfile(@compoundFileName, STGM_READWRITE OR STGM_CREATE OR STGM_SHARE_EXCLUSIVE, 0, @storage)

' Create two streams
DIM stream1 AS IStream PTR
DIM stream2 AS IStream PTR
DIM streamName1 AS WSTRING * 260 = "StreamImage1"
DIM streamName2 AS WSTRING * 260 = "StreamImage2"
storage->lpvtbl->CreateStream(storage, @streamName1, STGM_READWRITE Or STGM_SHARE_EXCLUSIVE, 0, 0, @stream1)
storage->lpvtbl->CreateStream(storage, @streamName2, STGM_READWRITE Or STGM_SHARE_EXCLUSIVE, 0, 0, @stream2)

' // Get encoder CLSIDs
DIM jpgClsid AS CLSID = AfxGdipGetEncoderClsid("image/jpeg")
DIM pngClsid AS CLSID = AfxGdipGetEncoderClsid("image/png")

' // Save images to streams
image1.Save(stream1, @jpgClsid, NULL)
image2.Save(stream2, @pngClsid, NULL)

PRINT "File saved"

PRINT
PRINT "Press any key"
SLEEP

SaveAdd (CGpImage)

Adds a frame to a file or stream specified in a previous call to the Save method.

FUNCTION SaveAdd (BYVAL encoderParams AS EncoderParameters PTR) AS GpStatus
FUNCTION SaveAdd (BYVAL pNewImage AS CGpImage PTR, BYVAL encoderParams AS EncoderParameters PTR) AS GpStatus

Return value

If the function succeeds, it returns StatusOk, which is an element of the GpStatus enumeration.

If the function fails, it returns one of the other elements of the GpStatus enumeration.

Example

' ========================================================================================
' Creating and Saving a Multiple-Frame Image
'
' With certain file formats, you can save multiple images (frames) to a single file. For
' example, you can save several pages to a single TIFF file. To save the first page, call
' the the Save method. To save subsequent pages, call the SaveAdd method.
' The following console application creates a TIFF file with three pages. The images that
' become the pages of the TIFF file come from three disk files. The code first constructs
' three Image objects: multi, page2 and page3. As the individual pages are added to the
' multiImage object, they are also added to the disk file Multiframe.tiff.
' Note that the code calls the Save method (not SaveAdd) to save the first page.
' ========================================================================================

DIM hStatus AS LONG

' // Create three image objects.
DIM multi AS CGpImage = "Shapes.bmp"
DIM page2 AS CGpImage = "Iron.jpg"
DIM page3 AS CGpImage = "House.png"

' // Get TIFF encoder CLSID
DIM clsid As CLSID = AfxGdipGetEncoderClsid("image/tiff")

' // Prepare EncoderParameters
DIM encoderParams As EncoderParameters
DIM paramValue As ULONG
encoderParams.Count = 1
encoderParams.Parameter(0).Guid = EncoderSaveFlag
encoderParams.Parameter(0).Type = EncoderParameterValueTypeLong
encoderParams.Parameter(0).NumberOfValues = 1
encoderParams.Parameter(0).Value = @paramValue

' // Save first frame
paramValue = EncoderValueMultiFrame
multi.Save("multiframe.tiff", @clsid, @encoderParams)

' // Add second frame
paramValue = EncoderValueFrameDimensionPage
multi.SaveAdd(@page2, @encoderParams)

' // Add third frame
paramValue = EncoderValueFrameDimensionPage
multi.SaveAdd(@page3, @encoderParams)

' // Finalize file
paramValue = EncoderValueFlush
hStatus = multi.SaveAdd(@encoderParams)

IF hStatus = StatusOk THEN PRINT "File saved" ELSE PRINT "Saving failed"

PRINT
PRINT "Press any key"
SLEEP

SelectActiveFrame (CGpImage)

Selects the frame in an Image object specified by a dimension and an index.

FUNCTION SelectActiveFrame (BYVAL dimensionID AS GUID PTR, BYVAL frameIndex AS UINT) AS GpStatus

Return value

If the function succeeds, it returns StatusOk, which is an element of the GpStatus enumeration.

If the function fails, it returns one of the other elements of the GpStatus enumeration.

Remarks

When you call the SelectActiveFrame method, all changes that you made to the previously active frame are discarded. If you want to retain changes that you make to a frame, call the Save method before you switch to a different frame.

Among all the image formats currently supported by GDI+, the only formats that support multiple-frame images are GIF and TIFF. When you call the SelectActiveFrame method on a GIF image, you should use FrameDimensionTime. When you call the SelectActiveFrame method on a TIFF image, you should use FrameDimensionPage.

SetPalette (CGpImage)

Sets the color palette of an Image object.

FUNCTION SetPalette (BYVAL pal AS ColorPalette PTR) AS GpStatus

Return value

If the function succeeds, it returns StatusOk, which is an element of the GpStatus enumeration.

If the function fails, it returns one of the other elements of the GpStatus enumeration.

Example

' ========================================================================================
' The SetImagePalette method sets a custom color palette for an image object in GDI+.
' This only applies to indexed pixel formats like 1bpp, 4bpp, or 8bpp images (e.g., GIFs or 8-bit BMPs).
' It replaces the image’s current palette with a new one you define.
' The palette must match the image’s pixel format (e.g., 256 colors for 8bpp).
' Useful for customizing color mapping, reducing color depth, or preparing images
' for formats that require indexed color.
' If you try to use it on a 24-bit or 32-bit image, it won’t work—those formats don’t use palettes.
' ========================================================================================

' Create a bitmap with 8bpp indexed format
DIM nWidth AS LONG = 64
DIM nHeight AS LONG = 64
DIM bmp AS CGpBitmap = CGpBitmap(nWidth, nHeight, 0, PixelFormat8bppIndexed, NULL)
IF bmp.GetLastStatus <> StatusOk THEN PRINT "Failed to create indexed bitmap" : END

' // Allocate and define a palette
DIM paletteSize AS LONG = SIZEOF(ColorPalette) + (256 * SIZEOF(ARGB))
DIM paletteBuffer AS UBYTE PTR = Allocate(paletteSize)
DIM paletteptr AS ColorPalette PTR = cast(ColorPalette PTR, paletteBuffer)
paletteptr->Flags = 0
paletteptr->Count = 256
FOR i AS LONG = 0 To 255
  paletteptr->Entries(i) = &HFF000000 OR (i SHL 16)  ' Shades of red
NEXT

' // Set the palette
bmp.SetPalette(paletteptr)
IF bmp.GetLastStatus = StatusOk THEN
   PRINT "Palette set successfully"
ELSE
   PRINT "Failed to set palette. Status = "; bmp.GetLastStatus
END IF

' // Cleanup
IF paletteBuffer THEN Deallocate(paletteBuffer)

PRINT
PRINT "Press any key"
SLEEP

SetPropertyItem (CGpImage)

Sets a property item (piece of metadata) for an Image object. If the item already exists, then its contents are updated; otherwise, a new item is added.

FUNCTION SetPropertyItem (BYVAL pitem AS PropertyItem PTR) AS GpStatus

Return value

If the function succeeds, it returns StatusOk, which is an element of the GpStatus enumeration.

If the function fails, it returns one of the other elements of the GpStatus enumeration.

Example

'#CONSOLE ON
#define _WIN32_WINNT &h0602
#INCLUDE ONCE "AfxNova/CGdiPlus.inc"
USING AfxNova

' ========================================================================================
' The following console application creates a Image object based on a JPEG file.
' The code calls the SetPropertyItem method of that Image object to set the title
' of the image.
' ========================================================================================

' // Create a Bitmap object from a JPEG file.
DIM image AS CGpImage = "BERRY_Halle_01.jpg"

' // Set new title
DIM titleText AS STRING = "Halle Berry"
DIM prop As PropertyItem
prop.id = PropertyTagImageTitle
prop.length = LEN(titleText) + 1  ' Include null terminator
prop.type = PropertyTagTypeASCII
prop.value = STRPTR(titleText)

IF image.SetPropertyItem(@prop) = StatusOk THEN
   PRINT "Title set successfully"
ELSE
   PRINT "Failed to set title"
 END IF

' // Get the encoder GUID for the .jpg image type
DIM clsidEncoder AS GUID = AfxGdipGetEncoderClsid("image/jpeg")
' // Save the file with another name
IF image.Save("modified.jpg", @clsidEncoder, NULL) = StatusOk THEN
   PRINT "File saved"
ELSE
   PRINT "Failed to save the file"
END IF

PRINT
PRINT "Press any key"
SLEEP

Constructors (CGpBitmap)

CONSTRUCTOR
CONSTRUCTOR (BYVAL pBitmap AS CGpBitmap PTR)
CONSTRUCTOR (BYVAL pwszFileName AS WSTRING PTR, BYVAL useEmbeddedColorManagement AS BOOLEAN = FALSE)
CONSTRUCTOR (BYVAL pStream AS IStream PTR, BYVAL useEmbeddedColorManagement AS BOOLEAN = FALSE)
CONSTRUCTOR (BYVAL nWidth AS INT_, BYVAL nHeight AS INT_, BYVAL stride AS INT_, _
            BYVAL pxFormat AS PixelFormat, BYVAL scan0 AS UBYTE PTR)
CONSTRUCTOR (BYVAL nWidth AS INT_, BYVAL nHeight AS INT_, BYVAL pxFormat AS PixelFormat = PixelFormat32bppPARGB)
CONSTRUCTOR (BYVAL nWidth AS INT_, BYVAL nHeight AS INT_, BYVAL pTarget AS CGpGraphics_ PTR)
CONSTRUCTOR (BYVAL gdiBitmapInfo AS BITMAPINFO PTR, BYVAL gdiBitmapData AS ANY PTR)
CONSTRUCTOR (BYVAL hbm AS HBITMAP, BYVAL hPal AS HPALETTE)
CONSTRUCTOR (BYVAL hicon AS HICON)
CONSTRUCTOR (BYVAL hInstance AS HINSTANCE, BYVAL pwszbitmapName AS WSTRING PTR)
CONSTRUCTOR (BYVAL surface AS IDirectDrawSurface7 PTR)

Creates a Bitmap object based on another Bitmap obejct (clones it).

Flat API function: GdipCloneImage

CONSTRUCTOR CGpBitmap (BYVAL pBitmap AS CGpBitmap PTR)

Example

' ========================================================================================
' The following example creates a Bitmap object from another image object.
' ========================================================================================
SUB Example_CloneConstructor (BYVAL hdc AS HDC)

   ' // Create a graphics object from the window device context
   DIM graphics AS CGpGraphics = hdc
   ' // Set the scaling factors using the DPI ratios
   graphics.ScaleTransformForDpi

   ' // Create a Bitmap object from a JPEG file.
   DIM myBitmap AS CGpBitmap = "climber.jpg"
   ' // Set the resolution of the image using the DPI ratios
   myBitmap.SetResolutionForDpi

   ' // Clone a portion of the bitmap.
   DIM cloneBitmap AS CGpBitmap = @myBitmap

   ' // Draw the clone.
   graphics.DrawImage(@cloneBitmap, 10, 10)

END SUB
' ========================================================================================

Creates a Bitmap object based on an image file.

CONSTRUCTOR (BYVAL pwszFileName AS WSTRING PTR, BYVAL useEmbeddedColorManagement AS BOOLEAN = FALSE)

Usage example

   ' // Create a graphics object from the window device context
   DIM graphics AS CGpGraphics = hdc
   ' // Set the scaling factors using the DPI ratios
   graphics.ScaleTransformForDpi

   ' // Create a Bitmap object from a JPEG file.
   DIM myBitmap AS CGpBitmap = "climber.jpg"
   ' // Set the resolution of the image using the DPI ratios
   myBitmap.SetResolutionForDpi

Creates a Bitmap object based on an IStream COM interface..

CONSTRUCTOR (BYVAL pStream AS IStream PTR, BYVAL useEmbeddedColorManagement AS BOOLEAN = FALSE)

Usage example

   ' // Create a graphics object from the window device context
   DIM graphics AS CGpGraphics = hdc
   ' // Set the scaling factors using the DPI ratios
   graphics.ScaleTransformForDpi

   ' // Create a Bitmap object from a JPEG file.
   DIM myBitmap AS CGpBitmap = pstream
   ' // Set the resolution of the image using the DPI ratios
   myBitmap.SetResolutionForDpi

Creates a Bitmap object based on a Graphics object, a width, and a height.

CONSTRUCTOR (BYVAL nWidth AS INT_, BYVAL nHeight AS INT_, BYVAL pTarget AS CGpGraphics_ PTR)

Example

' ========================================================================================
' This example creates a GpBitmap from a graphics object, inheriting DPI and rendering settings.
' ========================================================================================
SUB Example_CreateFromGraphics (BYVAL hdc AS HDC)

   ' // Create a graphics object from the window device context
   DIM graphics AS CGpGraphics = hdc
   ' // Set the scaling factors using the DPI ratios
   graphics.ScaleTransformForDpi

   ' // Create bitmap from graphics context
   DIM bmp AS CGpBitmap = CGpBitmap(200, 100, @graphics)

   ' // Create graphics object from bitmap
   DIM bmpGraphics AS CGpGraphics = @bmp

   ' // Fill bitmap with color
   bmpGraphics.Clear(ARGB_RED)

   ' // Draw the bitmap
   graphics.DrawImage(@bmp, 10, 10)

END SUB
' ========================================================================================

Creates a Bitmap object based on an array of bytes along with size and format information.

CONSTRUCTOR (BYVAL nWidth AS INT_, BYVAL nHeight AS INT_, BYVAL stride AS INT_, _
             BYVAL pxFormat AS PixelFormat, BYVAL scan0 AS UBYTE PTR)

Example

' ========================================================================================
' This example demonstrates how to create a GpBitmap object from a manually filled pixel
' buffer. It generates a 100×100 pixel image with a vertical gradient and renders it to
' the screen using GDI+.
' ========================================================================================
SUB Example_CreateFromScan0 (BYVAL hdc AS HDC)

   ' // Create a graphics object from the window device context
   DIM graphics AS CGpGraphics = hdc
   ' // Set the scaling factors using the DPI ratios
   graphics.ScaleTransformForDpi

   ' // Define dimensions and pixel format
   DIM nWidth AS LONG = 100
   DIM nHeight AS LONG = 100
   DIM bytesPerPixel AS LONG = 4
   DIM stride AS LONG = nWidth * bytesPerPixel

   ' // Allocate pixel buffer
   DIM buffer(stride * nHeight - 1) AS UBYTE
   ' // Fill buffer with a gradient
   FOR y AS LONG = 0 TO nHeight - 1
      FOR x AS LONG = 0 TO nWidth - 1
         DIM _offset AS LONGINT = y * stride + x * bytesPerPixel
         buffer(_offset + 0) = x * 255 \ nWidth    ' Blue
         buffer(_offset + 1) = y * 255 \ nHeight   ' Green
         buffer(_offset + 2) = 128                 ' Red
         buffer(_offset + 3) = 255                 ' Alpha
      NEXT
   NEXT

   ' // Create bitmap from buffer
   DIM bmp AS CGpBitmap = CGpBitmap(nWidth, nHeight, stride, PixelFormat32bppARGB, @buffer(0))

   ' // Draw the bitmap
   graphics.DrawImage(@bmp, 10, 10)

END SUB
' ========================================================================================

Creates a Bitmap object of a specified size and pixel format. The pixel data must be provided after the Bitmap object is constructed.

CONSTRUCTOR (BYVAL nWidth AS INT_, BYVAL nHeight AS INT_, BYVAL pxFormat AS PixelFormat = PixelFormat32bppPARGB)

Creates a Bitmap object based on a handle to a Windows Windows Graphics Device Interface (GDI) bitmap and a handle to a GDI palette.

CONSTRUCTOR (BYVAL hbm AS HBITMAP, BYVAL hPal AS HPALETTE = FALSE)

Flat API function: GdipCreateBitmapFromHBITMAP

Example

' ========================================================================================
' This example creates a GpBitmap from a legacy HBITMAP and renders it using GDI+.
' ========================================================================================
SUB Example_CreateFromHBITMAP (BYVAL hdc AS HDC)

   ' // Create a graphics object from the window device context
   DIM graphics AS CGpGraphics = hdc
   ' // Set the scaling factors using the DPI ratios
   graphics.ScaleTransformForDpi

   ' // Create a legacy HBITMAP using GDI
   DIM hbm AS HBITMAP
   DIM memDC AS HDC = CreateCompatibleDC(hdc)
   DIM bmpInfo AS BITMAPINFOHEADER
   bmpInfo.biSize = SIZEOF(BITMAPINFOHEADER)
   bmpInfo.biWidth = 100
   bmpInfo.biHeight = -100 ' Top-down
   bmpInfo.biPlanes = 1
   bmpInfo.biBitCount = 32
   bmpInfo.biCompression = BI_RGB
   bmpInfo.biSizeImage = 0

   DIM pBits AS ANY PTR
   hbm = CreateDIBSection(memDC, CAST(BITMAPINFO PTR, @bmpInfo), DIB_RGB_COLORS, @pBits, NULL, 0)

   ' // Fill with red pixels
   FOR i AS LONG = 0 TO 100 * 100 - 1
      CAST(ULONG PTR, pBits)[i] = ARGB_RED
   NEXT

   ' // Create GDI+ Bitmap from HBITMAP
   DIM bmp AS CGpBitmap = CGpBitmap(hbm)

   ' // Draw the bitmap
   graphics.DrawImage(@bmp, 10, 10)

END SUB
' ========================================================================================

Creates a Bitmap object based on a BITMAPINFO structure and an array of pixel data.

CONSTRUCTOR (BYVAL gdiBitmapInfo AS BITMAPINFO PTR, BYVAL gdiBitmapData AS ANY PTR)

Flat API function: GdipCreateBitmapFromGdiDib

Example

' ========================================================================================
' This example creates a GpBitmap from a manually constructed BITMAPINFO and pixel buffer.
' ========================================================================================
SUB Example_CreateFromGdiDib (BYVAL hdc AS HDC)

   ' // Create a graphics object from the window device context
   DIM graphics AS CGpGraphics = hdc
   ' // Set the scaling factors using the DPI ratios
   graphics.ScaleTransformForDpi

   ' // Define bitmap dimensions
   DIM nWidth AS LONG = 100
   DIM nHeight AS LONG = 100
   DIM bytesPerPixel AS LONG = 4
   DIM stride AS LONG = nWidth * bytesPerPixel

   ' // Allocate pixel buffer
   DIM buffer(stride * nHeight - 1) AS UBYTE

   ' // Fill buffer with gradient
   FOR y AS LONG = 0 TO nHeight - 1
      FOR x AS LONG = 0 TO nWidth - 1
         DIM offset AS LONG = y * stride + x * bytesPerPixel
         buffer(offset + 0) = x * 255 \ nWidth   ' Blue
         buffer(offset + 1) = y * 255 \ nHeight  ' Green
         buffer(offset + 2) = 128                ' Red
         buffer(offset + 3) = 255                ' Alpha
      NEXT
   NEXT

   ' // Define BITMAPINFO header
   DIM bmi AS BITMAPINFO
   WITH bmi.bmiHeader
      .biSize = SIZEOF(BITMAPINFOHEADER)
      .biWidth = nWidth
      .biHeight = -nHeight ' Top-down DIB
      .biPlanes = 1
      .biBitCount = 32
      .biCompression = BI_RGB
      .biSizeImage = stride * nHeight
      .biXPelsPerMeter = 39.3701 * graphics.GetDpiX
      .biYPelsPerMeter = 39.3701 * graphics.GetDpiY
   END WITH

   ' // Create bitmap from DIB
   DIM bmp AS CGpBitmap = CGpBitmap(@bmi, @buffer(0))

   ' // Draw the modified bitmap.
   graphics.DrawImage(@bmp, 10, 10)

END SUB
' ========================================================================================

Creates a Bitmap object based on an icon.

CONSTRUCTOR CGpBitmap (BYVAL hicon AS HICON)

Flat API function: GdipCreateBitmapFromHICON

Example

' ========================================================================================
' This example creates a GpBitmap from an icon and renders it using GDI+.
' ========================================================================================
SUB Example_CreateFromHICON (BYVAL hdc AS HDC)

   ' // Create a graphics object from the window device context
   DIM graphics AS CGpGraphics = hdc
   ' // Set the scaling factors using the DPI ratios
   graphics.ScaleTransformForDpi

   ' // Load a system icon (e.g., information icon)
   DIM hIcon AS HICON = LoadIcon(NULL, IDI_INFORMATION)

   ' // Create a GDI+ Bitmap from the HICON
   DIM bmp AS CGpBitmap = CGpBitmap(hIcon)

   ' // Draw the bitmap
   graphics.DrawImage(@bmp, 10, 10)

END SUB
' ========================================================================================

Creates a Bitmap object based on an application or DLL instance handle and the name of a bitmap resource.

CONSTRUCTOR CGpBitmap (BYVAL hInstance AS HINSTANCE, BYVAL pwszBitmapName AS WSTRING PTR)

Creates a Bitmap object based on a DirectDraw surface. The Bitmap object maintains a reference to the DirectDraw surface until the Bitmap object is deleted or goes out of scope.

CONSTRUCTOR (BYVAL surface AS IDirectDrawSurface7 PTR)

Flat API function: GdipCreateBitmapFromDirectDrawSurface

ApplyEffect (CGpBitmap)

Alters a Bitmap object by applying a specified effect.

FUNCTION ApplyEffect (BYVAL pEffect AS CGpEffect PTR, BYVAL roi AS RECT PTR = NULL) AS GpStatus
FUNCTION ApplyEffect (BYVAL pEffect AS CGpEffect PTR, BYVAL roi AS RECT PTR, _
   BYVAL useAuxData AS BOOLEAN, BYVAL auxData AS ANY PTR PTR, BYVAL auxDataSize AS INT_ PTR) AS GpStatus

Flat API function: GdipBitmapApplyEffect

Example

' ========================================================================================
' This example loads an image from disk and applies a blur effect using GDI+ 1.1.
' ========================================================================================
SUB Example_BlurEffect (BYVAL hdc AS HDC)

   ' // Create a graphics object from the window device context
   DIM graphics AS CGpGraphics = hdc
   ' // Set the scaling factors using the DPI ratios
   graphics.ScaleTransformForDpi

   ' // Create a Bitmap object from a JPEG file.
   DIM bmp AS CGpBitmap = "climber.jpg"
   ' // Set the resolution of the image using the DPI ratios
   bmp.SetResolutionForDpi

   ' // Create a blur effect
   DIM blurEffect AS CGpBlur
   ' // Set parameters: radius = 6.0, expandEdge = FALSE
   DIM blurPrms AS BlurParams = (6.0, FALSE)
   blurEffect.SetParameters(@blurPrms)
   ' // Apply effect to the whole image
   bmp.ApplyEffect(@blurEffect)

   ' // Draw the image
   graphics.DrawImage(@bmp, 10, 10)

END SUB
' ========================================================================================

Example

' ========================================================================================
' This example loads an image from disk and applies a brightness effect using GDI+ 1.1.
' ========================================================================================
SUB Example_Brightnessffect (BYVAL hdc AS HDC)

   ' // Create a graphics object from the window device context
   DIM graphics AS CGpGraphics = hdc
   ' // Set the scaling factors using the DPI ratios
   graphics.ScaleTransformForDpi

   ' // Create a Bitmap object from a JPEG file.
   DIM bmp AS CGpBitmap = "climber.jpg"
   ' // Set the resolution of the image using the DPI ratios
   bmp.SetResolutionForDpi

   ' // Create a brightness and contrast effect
   DIM brightnessEffect AS CGpBrightnessContrast
   ' // Set parameters: brightness = 50, contrast = 50
   DIM bcParams AS BrightnessContrastParams = (50, 20)
   brightnessEffect.SetParameters(@bcParams)
   ' // Apply effect to the whole image
   bmp.ApplyEffect(@brightnessEffect)

   ' // Draw the image
   graphics.DrawImage(@bmp, 10, 10)

END SUB
' ========================================================================================

Example

' ========================================================================================
' This example loads an image from disk and applies a sharpen effect using GDI+ 1.1.
' ========================================================================================
SUB Example_SharpenEffect (BYVAL hdc AS HDC)

   ' // Create a graphics object from the window device context
   DIM graphics AS CGpGraphics = hdc
   ' // Set the scaling factors using the DPI ratios
   graphics.ScaleTransformForDpi

   ' // Create a Bitmap object from a JPEG file.
   DIM bmp AS CGpBitmap = "climber.jpg"
   ' // Set the resolution of the image using the DPI ratios
   bmp.SetResolutionForDpi

   ' // Create a sharpen effect
   DIM sharpenEffect AS CGpSharpen
   ' // Set parameters: radius = 3.0, expandEdge = FALSE
   DIM sharpenParams AS SharpenParams = (3.0, FALSE)
   sharpenEffect.SetParameters(@sharpenParams)
   ' // Apply effect to the whole image
   bmp.ApplyEffect(@sharpenEffect)

   ' // Draw the image
   graphics.DrawImage(@bmp, 10, 10)

END SUB
' ========================================================================================

Example

' ========================================================================================
' This example loads an image from disk and applies a red eyes correction effect using GDI+ 1.1.
' ========================================================================================
SUB Example_BitmapRedEyeCorrectionEffect (BYVAL hdc AS HDC)

   ' // Create a graphics object from the window device context
   DIM graphics AS CGpGraphics = hdc
   ' // Set the scaling factors using the DPI ratios
   graphics.ScaleTransformForDpi

   ' // Create a Bitmap object from a JPEG file.
   DIM bmp AS CGpBitmap = "RedEyes.jpg"
   ' // Set the resolution of the image using the DPI ratios
   bmp.SetResolutionForDpi

   ' // Create a red eyes correction effect
   DIM redEyeEffect AS CGpRedEyeCorrection

   ' // We need to specify one or more rectangles that enclose the red-eye areas.
   ' // These are passed as an array of RECT structures.

   ' // Define two rectangles around the eyes
   ' // Change the values according the coordinates of your image
   DIM eyeRects(0 TO 1) AS RECT
   eyeRects(0).left   =   1 : eyeRects(0).top    =   1
   eyeRects(0).right  = 400 : eyeRects(0).bottom = 250
   eyeRects(1).left   =   1 : eyeRects(1).top    =   1
   eyeRects(1).right  = 400 : eyeRects(1).bottom = 250

   ' // Fill a RedEyeCorrectionParams structure
   DIM redeyeParams AS RedEyeCorrectionParams
   redeyeParams.numberOfAreas = 2
   redeyeParams.areas = @eyeRects(0)
   ' // Calculate the size of the paameters
   DIM paramsSize AS UINT = SIZEOF(RedEyeCorrectionParams) + redeyeParams.numberOfAreas * SIZEOF(RECT)
   ' // Set the parameters
   redEyeEffect.SetParameters(@redeyeParams)

   ' // Apply effect to the whole image
   bmp.ApplyEffect(@redEyeEffect)

   ' // Draw the image
   graphics.DrawImage(@bmp, 5, 5)

END SUB
' ========================================================================================

Example

' ========================================================================================
' The HueSaturationLightness effecty enables you to change the hue, saturation, and lightness
' of a bitmap. To specify the magnitudes of the changes in hue, saturation, and lightness,
' pass a HueSaturationLightnessParams structure to the SetParameters method.
' ========================================================================================
SUB Example_BitmapHueSaturationLightnessEffect (BYVAL hdc AS HDC)

   ' // Create a graphics object from the window device context
   DIM graphics AS CGpGraphics = hdc
   ' // Set the scaling factors using the DPI ratios
   graphics.ScaleTransformForDpi

   ' // Create a Bitmap object from a JPEG file.
   DIM bmp AS CGpBitmap = "climber.jpg"
   ' // Set the resolution of the image using the DPI ratios
   bmp.SetResolutionForDpi

   ' // Create a HueSaturationLightness effect
   DIM hueEffect AS CGpHueSaturationLightness
   ' // Set the parameters
   DIM hslParams AS HueSaturationLightnessParams
   hslParams.hueLevel = 45            ' Rotate hue slightly
   hslParams.saturationLevel = 30     ' Boost saturation
   hslParams.lightnessLevel = -10     ' Slightly darken
   hueEffect.SetParameters(@hslParams)

   ' // Apply effect to the whole image
   bmp.ApplyEffect(@hueEffect)

   ' // Draw the image
   graphics.DrawImage(@bmp, 10, 10)

END SUB
' ========================================================================================

Example

' ========================================================================================
' The Levels effect encompasses three bitmap adjustments: highlight, midtone, and shadow.
' You can apply one or more of those adjustments to a bitmap by passing calling the
' ApplyEffect method. To specify the intensities of the adjustments, pass the
' address of a LevelsParams structure to the SetParameters method.
' ========================================================================================
SUB Example_LevelsEffect (BYVAL hdc AS HDC)

   ' // Create a graphics object from the window device context
   DIM graphics AS CGpGraphics = hdc
   ' // Set the scaling factors using the DPI ratios
   graphics.ScaleTransformForDpi

   ' // Create a Bitmap object from a JPEG file.
   DIM bmp AS CGpBitmap = "climber.jpg"
   ' // Set the resolution of the image using the DPI ratios
   bmp.SetResolutionForDpi

   ' // Create a levels effect
   DIM levelsEffect AS CGpLevels
   ' // Set the parameters
   DIM levelsParams AS LevelsParams
   levelsParams.highlight =  20    ' Boost highlights
   levelsParams.midtone   =  10    ' Slightly brighten midtones
   levelsParams.shadow    = -15    ' Deepen shadows
   levelsEffect.SetParameters(@levelsParams)

   ' // Apply effect to the whole image
   bmp.ApplyEffect(@levelsEffect)

   ' // Draw the image
   graphics.DrawImage(@bmp, 10, 10)

END SUB
' ========================================================================================

Example

' ========================================================================================
' The Tint effect enables you to apply a tint to a bitmap. To specify the nature of the tint,
' pass the address of a TintParams structure to the SetParameters method.
' ========================================================================================
SUB Example_TintEffect (BYVAL hdc AS HDC)

   ' // Create a graphics object from the window device context
   DIM graphics AS CGpGraphics = hdc
   ' // Set the scaling factors using the DPI ratios
   graphics.ScaleTransformForDpi

   ' // Create a Bitmap object from a JPEG file.
   DIM bmp AS CGpBitmap = "climber.jpg"
   ' // Set the resolution of the image using the DPI ratios
   bmp.SetResolutionForDpi

   ' // Create a tint effect
   DIM tintEffect AS CGpTint
   ' // Set parameters: Hue = +120 (green), Amount = 60 (moderate tint)
   DIM tintPrms AS TintParams = (120, 60)
   tintEffect.SetParameters(@tintPrms)
   ' // Apply effect to the whole image
   bmp.ApplyEffect(@tintEffect)

   ' // Draw the image
   graphics.DrawImage(@bmp, 10, 10)

END SUB
' ========================================================================================

Example

' ========================================================================================
' The ColorLUT effect lets you define lookup tables for each channel—Alpha, Red, Green,
' and Blue—with 256 entries each. For every pixel in the image:
' The channel value (0–255) is used as an index.
' The corresponding value in the LUT replaces the original.
' This means you can:
' Invert colors
' Apply posterization
' Simulate film-like grading
' Create custom stylizations
' ========================================================================================
SUB Example_ColorLUTEffect (BYVAL hdc AS HDC)

   ' // Create a graphics object from the window device context
   DIM graphics AS CGpGraphics = hdc
   ' // Set the scaling factors using the DPI ratios
   graphics.ScaleTransformForDpi

   ' // Create a Bitmap object from a JPEG file.
   DIM bmp AS CGpBitmap = "climber.jpg"
   ' // Set the resolution of the image using the DPI ratios
   bmp.SetResolutionForDpi

   ' // Create a ColorLUT effect
   DIM colorLUTEffect AS CGpColorLUT

   ' // Create LUTs: identity (no change)
   DIM lut AS ColorLUTParams
   FOR i AS LONG = 0 TO 255
      lut.lutB(i) = i
      lut.lutG(i) = i
      lut.lutR(i) = i
      lut.lutA(i) = i
   NEXT

   ' // Example: invert red channel
   FOR i AS LONG = 0 TO 255
      lut.lutR(i) = 255 - i
   NEXT

   ' // Set parameters
   colorLUTEffect.SetParameters(@lut)

   ' // Apply effect to the whole image
   bmp.ApplyEffect(@colorLUTEffect)

   ' // Draw the image
   graphics.DrawImage(@bmp, 10, 10)

END SUB
' ========================================================================================

Example

' ========================================================================================
' The ColorLUT effect lets you define lookup tables for each channel—Alpha, Red, Green,
' and Blue—with 256 entries each. For every pixel in the image:
' The channel value (0–255) is used as an index.
' The corresponding value in the LUT replaces the original.
' This means you can:
' Invert colors
' Apply posterization
' Simulate film-like grading
' Create custom stylizations
' The following example applies the effect to the specified region only.
' ========================================================================================
SUB Example_ColorLUTEffectRegion (BYVAL hdc AS HDC)

   ' // Create a graphics object from the window device context
   DIM graphics AS CGpGraphics = hdc
   ' // Set the scaling factors using the DPI ratios
   graphics.ScaleTransformForDpi

   ' // Create a Bitmap object from a JPEG file.
   DIM bmp AS CGpBitmap = "climber.jpg"
   ' // Set the resolution of the image using the DPI ratios
   bmp.SetResolutionForDpi

   ' // Create a ColorLut effect
   DIM colorLUTEffect AS CGpColorLUT

   ' // Create LUTs: identity (no change)
   DIM lut AS ColorLUTParams
   FOR i AS LONG = 0 TO 255
      lut.lutB(i) = i
      lut.lutG(i) = i
      lut.lutR(i) = i
      lut.lutA(i) = i
   NEXT

   ' // Example: invert red channel
   FOR i AS LONG = 0 TO 255
      lut.lutR(i) = 255 - i
   NEXT

   ' // Set parameters
   colorLUTEffect.SetParameters(@lut)

   ' // Define the region of interest (ROI)
   DIM roi AS RECT
   roi.left   = 20
   roi.top    = 20
   roi.right  = 150
   roi.bottom = 100

   ' // Apply effect to the whole image
   bmp.ApplyEffect(@colorLUTEffect, @roi)

   ' // Draw the image
   graphics.DrawImage(@bmp, 10, 10)

END SUB
' ========================================================================================

Example

' ========================================================================================
' Converts the image to grayscale by averaging RGB channels.
' ========================================================================================
SUB Example_GrayScaleEffect (BYVAL hdc AS HDC)

   ' // Create a graphics object from the window device context
   DIM graphics AS CGpGraphics = hdc
   ' // Set the scaling factors using the DPI ratios
   graphics.ScaleTransformForDpi

   ' // Create a Bitmap object from a JPEG file.
   DIM bmp AS CGpBitmap = "climber.jpg"
   ' // Set the resolution of the image using the DPI ratios
   bmp.SetResolutionForDpi

   ' // Create grayscale matrix
   DIM grayMatrix(0 TO 4, 0 TO 4) AS SINGLE = {{0.3, 0.3, 0.3, 0.0, 0.0}, _
      {0.59, 0.59, 0.59, 0.0, 0.0}, {0.11, 0.11, 0.11, 0.0, 0.0}, _
      {0.0, 0.0, 0.0, 1.0, 0.0}, {0.0, 0.0, 0.0, 0.0, 1.0}}

   ' // Create a gray matrix effect
   DIM grayEffect AS CGpColorMatrix
   ' // Set parameters
   grayEffect.SetParameters(cast(ColorMatrix PTR, @grayMatrix(0, 0)))
   ' // Apply effect to the whole image
   bmp.ApplyEffect(@grayEffect)

   ' // Draw the image
   graphics.DrawImage(@bmp, 10, 10)

END SUB
' ========================================================================================

Clone (CGpBitmap)

Creates a new Bitmap object from another Bitmap object (clones it).

FUNCTION Clone (BYVAL pCloneBitmap AS CGpBitmap PTR) AS GpStatus

Creates a new Bitmap object by copying a portion of this bitmap.

FUNCTION Clone (BYVAL x AS SINGLE, BYVAL y AS SINGLE, BYVAL nWidth AS SINGLE, _
   BYVAL nHeight AS SINGLE, BYVAL pxFormat AS PixelFormat, BYVAL pCloneBitmap AS CGpBitmap PTR) AS GpStatus
FUNCTION Clone (BYVAL x AS SINGLE, BYVAL y AS SINGLE, BYVAL nWidth AS SINGLE, _
   BYVAL nHeight AS SINGLE, BYVAL pxFormat AS PixelFormat) AS CGpBitmap
FUNCTION Clone (BYVAL rc AS GpRectF PTR, BYVAL pxFormat AS PixelFormat, _
   BYVAL pCloneBitmap AS CGpBitmap PTR) AS GpStatus
FUNCTION Clone (BYVAL rc AS GpRect PTR, BYVAL pxFormat AS PixelFormat, _
   BYVAL pCloneBitmap AS CGpBitmap PTR) AS GpStatus

Return value

If the function succeeds, it returns StatusOk, which is an element of the GpStatus enumeration.

If the function fails, it returns one of the other elements of the GpStatus enumeration.

Flat API functions: GdipCloneImage and GdipCloneBitmapArea

Example

' ========================================================================================
' The following example creates a Bitmap from an image file, clones the upper-left
' portion of the image, and then draws the cloned image.
' ========================================================================================
SUB Example_CloneArea (BYVAL hdc AS HDC)

   ' // Create a graphics object from the window device context
   DIM graphics AS CGpGraphics = hdc
   ' // Get the DPI scaling ratio
   DIM rxRatio AS SINGLE = graphics.GetDpiX / 96
   DIM ryRatio AS SINGLE = graphics.GetDpiY / 96

   ' // Create a Bitmap object from a JPEG file.
   DIM myBitmap AS CGpBitmap = "climber.jpg"

   ' // Clone a portion of the bitmap.
   DIM cloneBitmap AS CGpBitmap
   myBitmap.Clone(0, 0, 100, 100, PixelFormatDontCare, @cloneBitmap)

   ' // Draw the clone.
   graphics.DrawImage(@cloneBitmap, 0, 0)

END SUB
' ========================================================================================

ConvertFormat (CGpBitmap)

Converts a bitmap to a specified pixel format. The original pixel data in the bitmap is replaced by the new pixel data.

FUNCTION ConvertFormat (BYVAL pxFormat AS PixelFormat, BYVAL nDitherType AS DitherType, _
   BYVAL nPaletteType AS PaletteType, BYVAL colourPalette AS ColorPalette PTR, _
   BYVAL alphaThresholdPercent AS SINGLE) AS GpStatus

Return value

If the function succeeds, it returns StatusOk, which is an element of the GpStatus enumeration.

If the function fails, it returns one of the other elements of the GpStatus enumeration.

Flat API function: GdipBitmapConvertFormat

Example

' ========================================================================================
' The CGpBitmap ConvertFormat method wraps the GdipBitmapConvertFormat, which is a GDI+ 1.1
' function that converts the pixel format of an existing bitmap to another format—such as
' from 32bpp ARGB to 8bpp indexed. It replaces the original pixel data with new data that
' matches the target format.
' ========================================================================================
SUB Example_ConvertFormat (BYVAL hdc AS HDC)

   ' // Create a graphics object from the window device context
   DIM graphics AS CGpGraphics = hdc
   ' // Set the scaling factors using the DPI ratios
   graphics.ScaleTransformForDpi

   ' // Create original bitmap from buffer
   DIM nWidth AS LONG = 100
   DIM nHeight AS LONG = 100
   DIM bytesPerPixel AS LONG = 4
   DIM stride AS LONG = nWidth * bytesPerPixel
   DIM buffer(stride * nHeight - 1) AS UBYTE

   FOR y AS LONG = 0 TO nHeight - 1
      FOR x AS LONG = 0 TO nWidth - 1
         DIM offset AS LONGINT = y * stride + x * bytesPerPixel
         buffer(offset + 0) = x * 255 \ nWidth    ' Blue
         buffer(offset + 1) = y * 255 \ nHeight   ' Green
         buffer(offset + 2) = 128                 ' Red
         buffer(offset + 3) = 255                 ' Alpha
      NEXT
   NEXT

   DIM bmp AS CGpBitmap = CGpBitmap(nWidth, nHeight, stride, PixelFormat32bppARGB, @buffer(0))

   ' // Convert to 8bpp indexed format
   bmp.ConvertFormat(PixelFormat8bppIndexed, DitherTypeNone, PaletteTypeFixedHalftone216, NULL, 0)

   ' // Draw the converted bitmap.
   graphics.DrawImage(@bmp, 10, 10)

END SUB
' ========================================================================================

GetHBITMAP (CGpBitmap)

Creates a Windows Graphics Device Interface (GDI) bitmap from this Bitmap object.

FUNCTION GetHBITMAP (BYVAL colorBackground AS ARGB, BYVAL hbmReturn AS HBITMAP PTR) AS GpStatus

Return value

If the function succeeds, it returns StatusOk, which is an element of the GpStatus enumeration.

If the function fails, it returns one of the other elements of the GpStatus enumeration.

Flat API function: GdipCreateHBITMAPFromBitmap

Example

' ========================================================================================
' This example converts a GDI+ Bitmap into a legacy HBITMAP and draws it using GDI.
' ========================================================================================
SUB Example_GetHBITMAP (BYVAL hdc AS HDC)

   ' // Create a graphics object from the window device context
   DIM graphics AS CGpGraphics = hdc

   ' // Create a Bitmap object from a JPEG file.
   DIM bmp AS CGpBitmap = "climber.jpg"
   ' // Set the resolution of the image using the DPI ratios
   bmp.SetResolutionForDpi

   ' // Convert to HBITMAP
   DIM hbm AS HBITMAP = bmp.GetHBITMAP(ARGB_WHITE)

   ' // Draw using classic GDI
   DIM memDC AS HDC = CreateCompatibleDC(hdc)
   DIM oldBmp AS HBITMAP = SelectObject(memDC, hbm)

   ' // Retrieve bitmap dimensions from HBITMAP
   DIM bmpInfo AS BITMAP
   GetObject(hbm, SIZEOF(BITMAP), @bmpInfo)

   ' // Apply DPI scaling
   DIM scaledWidth AS LONG = bmpInfo.bmWidth * graphics.GetDpiX / 96
   DIM scaledHeight AS LONG = bmpInfo.bmHeight * graphics.GetDpiY / 96
   StretchBlt(hdc, 0, 0, scaledWidth, scaledHeight, memDC, 0, 0, bmpInfo.bmWidth, bmpInfo.bmHeight, SRCCOPY)

   ' // Cleanup
   SelectObject(memDC, oldBmp)     ' Restore previous bitmap
   DeleteObject(hbm)               ' Delete the HBITMAP
   DeleteDC(memDC)                 ' Delete the memory DC

END SUB
' ========================================================================================

GetHICON (CGpBitmap)

Creates an icon from this Bitmap object.

FUNCTION GetHICON (BYVAL hiconReturn AS HICON PTR) AS GpStatus

Return value

If the function succeeds, it returns StatusOk, which is an element of the GpStatus enumeration.

If the function fails, it returns one of the other elements of the GpStatus enumeration.

Flat API function: GdipCreateHICONFromBitmap

Example

' ========================================================================================
' This example converts a GDI+ Bitmap into a Windows HICON and displays it.
' ========================================================================================
SUB Example_GetHICON (BYVAL hdc AS HDC)

   ' // Create a graphics object from the window device context
   DIM graphics AS CGpGraphics = hdc

   ' // Create a Bitmap object from a JPEG file.
   DIM bmp AS CGpBitmap = "climber.jpg"
   ' // Set the resolution of the image using the DPI ratios
   bmp.SetResolutionForDpi

   ' // Convert to HBITMAP
   DIM hIcon AS HICON = bmp.GetHICON

   ' // Get width and height of the icon
   DIM iconInfo AS ICONINFO
   DIM iconWidth AS LONG
   DIM iconHeight AS LONG
   IF GetIconInfo(hIcon, @iconInfo) THEN
      DIM bmp AS BITMAP
      IF iconInfo.hbmColor THEN
         ' Icon has a color bitmap
         GetObject(iconInfo.hbmColor, SIZEOF(BITMAP), @bmp)
         iconWidth = bmp.bmWidth
         iconHeight = bmp.bmHeight
         DeleteObject(iconInfo.hbmColor)
      ELSEIF iconInfo.hbmMask THEN
         ' Monochrome icon: height is double, so divide by 2
         GetObject(iconInfo.hbmMask, SIZEOF(BITMAP), @bmp)
         iconWidth = bmp.bmWidth
         iconHeight = bmp.bmHeight \ 2
      END IF
      IF iconInfo.hbmMask THEN DeleteObject(iconInfo.hbmMask)
   END IF

   ' // Scale it according to the DPI settings
   DIM scaledWidth AS LONG = iconWidth * graphics.GetDpiX / 96
   DIM scaledHeight AS LONG = iconHeight * graphics.GetDpiY / 96

   ' // Draw the icon
   DrawIconEx(hdc, 0, 0, hIcon, scaledWidth, scaledHeight, 0, NULL, DI_NORMAL)

   ' // Cleanup
   DestroyIcon(hIcon)

END SUB
' ========================================================================================

GetHistogram (CGpBitmap)

Returns one or more histograms for specified color channels of this Bitmap object.

FUNCTION GetHistogram (BYVAL nFormat AS HistogramFormat, BYVAL NumberOfEntries AS UINT, _
   BYVAL channel0 AS UINT PTR, BYVAL channel1 AS UINT PTR, BYVAL channel2 AS UINT PTR, _
   BYVAL channel3 AS UINT PTR) AS GpStatus

Return value

If the function succeeds, it returns StatusOk, which is an element of the GpStatus enumeration.

If the function fails, it returns one of the other elements of the GpStatus enumeration.

Remarks

The number of histograms returned depends on the HistogramFormat enumeration element passed to the format parameter. For example, if format is equal to HistogramFormatRGB, then three histograms are returned: one each for the red, green, and blue channels. In that case, channel0 points to the array that receives the red-channel histogram, channel1 points to the array that receives the green-channel histogram, and channel2 points to the array that receives the blue-channel histogram. For HistogramFormatRGB, channel3 must be set to NULL because there is no fourth histogram. For more details, see the HistogramFormat enumeration.

Flat API function: GdipBitmapGetHistogram

Example

' ========================================================================================
' This example loads an image from disk and gets the histogram.
' ========================================================================================
SUB Example_GetHistogram (BYVAL hdc AS HDC)

   ' // Create a graphics object from the window device context
   DIM graphics AS CGpGraphics = hdc
   ' // Set the scale transform to the DPI ratios
   graphics.ScaleTransformForDpi

   ' // Create a Bitmap object from a JPEG file.
   DIM bmp AS CGpBitmap = "climber.jpg"
   ' // Set the resolution of the image using the DPI ratios
   bmp.SetResolutionForDpi

   ' // Get histogram size
   DIM entries AS UINT = bmp.GetHistogramSize(HistogramFormatARGB)

   ' // Allocate histogram arrays
   DIM red(entries - 1) AS UINT
   DIM green(entries - 1) AS UINT
   DIM blue(entries - 1) AS UINT
   DIM alpha(entries - 1) AS UINT

   ' // Extract histograms
   bmp.GetHistogram(HistogramFormatARGB, entries, @red(0), @green(0), @blue(0), @alpha(0))

   ' // Example: print peak red value
   DIM maxRed AS UINT = 0
   FOR i AS UINT = 0 TO entries - 1
      IF red(i) > maxRed THEN maxRed = red(i)
   NEXT
   AfxMsg ("Max red intensity count: " & WSTR(maxRed))

   ' // Draw the image
   graphics.DrawImage(@bmp, 0, 0)

END SUB
' ========================================================================================

GetHistogramSize (CGpBitmap)

Returns the number of elements (in an array of DWORDs) that you must allocate before you call the GetHistogram method of a Bitmap object.

FUNCTION GetHistogramSize (BYVAL nFormat AS HistogramFormat, BYVAL NumberOfEntries AS UINT PTR) AS GpStatus

Return value

If the function succeeds, it returns StatusOk, which is an element of the GpStatus enumeration.

If the function fails, it returns one of the other elements of the GpStatus enumeration.

Flat API function: GdipBitmapGetHistogramSize

Usage example

' ========================================================================================
' This example loads an image from disk and gets the histogram.
' ========================================================================================
SUB Example_GetHistogram (BYVAL hdc AS HDC)

   ' // Create a graphics object from the window device context
   DIM graphics AS CGpGraphics = hdc
   ' // Set the scale transform to the DPI ratios
   graphics.ScaleTransformForDpi

   ' // Create a Bitmap object from a JPEG file.
   DIM bmp AS CGpBitmap = "climber.jpg"
   ' // Set the resolution of the image using the DPI ratios
   bmp.SetResolutionForDpi

   ' // Get histogram size
   DIM entries AS UINT = bmp.GetHistogramSize(HistogramFormatARGB)

   ' // Allocate histogram arrays
   DIM red(entries - 1) AS UINT
   DIM green(entries - 1) AS UINT
   DIM blue(entries - 1) AS UINT
   DIM alpha(entries - 1) AS UINT

   ' // Extract histograms
   bmp.GetHistogram(HistogramFormatARGB, entries, @red(0), @green(0), @blue(0), @alpha(0))

   ' // Example: print peak red value
   DIM maxRed AS UINT = 0
   FOR i AS UINT = 0 TO entries - 1
      IF red(i) > maxRed THEN maxRed = red(i)
   NEXT
   AfxMsg ("Max red intensity count: " & WSTR(maxRed))

   ' // Draw the image
   graphics.DrawImage(@bmp, 0, 0)

END SUB
' ========================================================================================

GetPixel (CGpBitmap)

Gets the color of a specified pixel in this bitmap.

FUNCTION GetPixel (BYVAL x AS LONG, BYVAL y AS LONG) AS ARGB
FUNCTION GetPixel (BYVAL x AS LONG, BYVAL y AS LONG, BYVAL colour AS ARGB PTR) AS GpStatus

Return value

First overloaded function: Returns the color value.

Second overloaded function: If the function succeeds, it returns StatusOk, which is an element of the GpStatus enumeration. If the function fails, it returns one of the other elements of the GpStatus enumeration.

Remarks

Depending on the format of the bitmap, GetPixel might not return the same value as was set by SetPixel. For example, if you call SetPixel on a Bitmap object whose pixel format is 32bppPARGB, the pixel’s RGB components are premultiplied. A subsequent call to GetPixel might return a different value because of rounding. Also, if you call SetPixel on a Bitmap object whose color depth is 16 bits per pixel, information could be lost during the conversion from 32 to 16 bits, and a subsequent call to GetPixel might return a different value.

Flat API function: GdipBitmapGetPixel

Example

' ========================================================================================
' The following example creates a Bitmap object based on a JPEG file. The code calls the
' GetPixel method to obtain the color of a pixel in the bitmap and then fills a rectangle
' with the retrieved color.
' ========================================================================================
SUB Example_GetPixel (BYVAL hdc AS HDC)

   ' // Create a graphics object from the window device context
   DIM graphics AS CGpGraphics = hdc
   ' // Set the scaling factors using the DPI ratios
   graphics.ScaleTransformForDpi

   ' // Create a Bitmap object from a JPEG file.
   DIM myBitmap AS CGpBitmap = "climber.jpg"

   ' // Fill a rectangle with the pixel color.
   DIM brush AS CGpSolidBrush = myBitmap.GetPixel(50, 50)
   graphics.FillRectangle(@brush, 10, 10, 100, 100)

END SUB
' ========================================================================================

InitializePalette (CGpBitmap)

Initializes a standard, optimal, or custom color palette.

FUNCTION InitializePalette (BYVAL colourPalette AS ColorPalette PTR, BYVAL nPaletteType AS PaletteType, _
   BYVAL optimalColors AS INT_, BYVAL useTransparentColor AS BOOL, BYVAL pBitmap AS CGpBitmap PTR) AS GpStatus

Return value

If the function succeeds, it returns StatusOk, which is an element of the GpStatus enumeration.

If the function fails, it returns one of the other elements of the GpStatus enumeration.

Flat API format: GdipInitializePalette

LockBits (CGpBitmap)

Locks a rectangular portion of this bitmap and provides a temporary buffer that you can use to read or write pixel data in a specified format. Any pixel data that you write to the buffer is copied to the Bitmap object when you call UnlockBits.

FUNCTION LockBits (BYVAL rc AS GpRect PTR, BYVAL flags AS UINT, BYVAL pxFormat AS PixelFormat, _
   BYVAL lockedBitmapData AS BitmapData PTR) AS GpStatus

Return value

If the function succeeds, it returns StatusOk, which is an element of the GpStatus enumeration.

If the function fails, it returns one of the other elements of the GpStatus enumeration.

Flat API function: GdipBitmapLockBits

Remarks

Use the LockBits method to lock an existing bitmap in system memory so that it can be changed programmatically. You can change the color of an image with the SetPixel method, although the LockBits method offers better performance for large-scale changes.

The BitmapData specifies the attributes of the Bitmap, such as size, pixel format, the starting address of the pixel data in memory, and length of each scan line (stride).

Example

' ========================================================================================
' Demonstrates the use of GdipBitmapLockBits/GdipBitmapUnlockBits.
' This example inverts the colors of a Bitmap.
' ========================================================================================
SUB Example_LockBits (BYVAL hdc AS HDC)

   ' // Create a graphics object from the window device context
   DIM graphics AS CGpGraphics = hdc
   ' // Set the scaling factors using the DPI ratios
   graphics.ScaleTransformForDpi

   ' // Create a Bitmap object from a JPEG file.
   DIM bmp AS CGpBitmap = "climber.jpg"
   ' // Set the resolution of the image using the DPI ratios
   bmp.SetResolutionForDpi

   ' // Get the width and height of the bitmap
   DIM nWidth AS DWORD = bmp.GetWidth
   DIM nHeight AS DWORD = bmp.GetHeight

   ' // Define lock rectangle
   DIM rc AS GpRect = (0, 0, nWidth, nHeight)

   ' // Lock bitmap bits
   DIM bmpData AS BitmapData
   bmp.LockBits(@rc, ImageLockModeRead OR ImageLockModeWrite, PixelFormat32bppARGB, @bmpData)
   ' // Alternate way
   ' DIM bmpData AS BitmapData = bmp.LockBits(@rc, ImageLockModeRead OR ImageLockModeWrite, PixelFormat32bppARGB)

   ' // Invert colors
   DIM pPixels AS UBYTE PTR = bmpData.Scan0
   FOR y AS LONG = 0 TO nHeight - 1
      FOR x AS LONG = 0 TO nWidth - 1
         DIM offset AS LONG = y * bmpData.Stride + x * 4
         pPixels[offset + 0] = 255 - pPixels[offset + 0] ' Blue
         pPixels[offset + 1] = 255 - pPixels[offset + 1] ' Green
         pPixels[offset + 2] = 255 - pPixels[offset + 2] ' Red
         ' Alpha remains unchanged
      NEXT
   NEXT

   ' // Unlock bitmap bits
   bmp.UnlockBits(@bmpData)

   ' // Draw the modified bitmap.
   graphics.DrawImage(@bmp, 10, 10)

END SUB
' ========================================================================================

Example

' ========================================================================================
' This example sets every third byte to 255 (red tint for 24bpp images)
' ========================================================================================
SUB Example_LockBits (BYVAL hdc AS HDC)

   ' // Create a graphics object from the window device context
   DIM graphics AS CGpGraphics = hdc
   ' // Set the scaling factors using the DPI ratios
   graphics.ScaleTransformForDpi

   ' // Create a Bitmap object from a JPEG file.
   DIM bmp AS CGpBitmap = "climber.jpg"
   ' // Set the resolution of the image using the DPI ratios
   bmp.SetResolutionForDpi

   ' // Define rectangle to lock
   DIM rc AS GpRect = (0, 0, bmp.GetWidth, bmp.GetHeight)

   ' // Lock bitmap bits
   DIM bmpData AS BitmapData = bmp.LockBits(@rc, ImageLockModeRead OR ImageLockModeWrite, bmp.GetPixelFormat)

   ' // Get pointer to pixel data
   DIM ptrData AS UBYTE PTR = bmpData.Scan0

   ' // Calculate total bytes
   DIM bytes AS LONG = ABS(bmpData.Stride) * bmp.GetHeight

   ' // Copy pixel data to array
   DIM rgbValues(bytes - 1) AS UBYTE
   CopyMemory(@rgbValues(0), ptrData, bytes)

   ' // Modify pixel data: set every third byte to 255
   FOR i AS LONG = 2 TO bytes - 1 STEP 3
      rgbValues(i) = 255
   NEXT

   ' // Copy modified data back
   CopyMemory(ptrData, @rgbValues(0), bytes)

   ' // Unlock bitmap
   bmp.UnlockBits(@bmpData)

   ' // Draw result
   graphics.DrawImage(@bmp, 10, 10)

END SUB
' ========================================================================================

MakeTransparent (CGpBitmap)

Makes the default transparent color (light gray) or the specified color transparent for this Bitmap.

FUNCTION MakeTransparent () AS GpStatus
FUNCTION MakeTransparent (BYVAL transparentColor AS ARGB) AS GpStatus

The system palette defines one color as the default transparent, or alpha, color. This method makes the default transparent color transparent for this Bitmap. If no transparent color is specified by the system, light gray is the transparent color.

When you call MakeTransparent, the bitmap will be converted to the Format32bppArgb format, as this format supports an alpha channel.

Example

' ========================================================================================
' This example makes the system default transparent color transparent for myBitmap, and
' then draws the Bitmap to the screen.
' ========================================================================================
SUB Example_MakeTransparent (BYVAL hdc AS HDC)

   ' // Create a graphics object from the window device context
   DIM graphics AS CGpGraphics = hdc
   ' // Set the scaling factors using the DPI ratios
   graphics.ScaleTransformForDpi

   ' // Create a Bitmap object from a JPEG file.
   DIM myBitmap AS CGpBitmap = "HouseAndTree.gif"

   ' // Make the red color transparent
   myBitmap.MakeTransparent
   ' // Alternative: Make the specified color transparent
'   myBitmap.MakeTransparent(ARGB_RED)

   ' // Draw the image
   graphics.DrawImage(@myBitmap, 10, 10)

END SUB
' ========================================================================================

SetPixel (CGpBitmap)

Sets the color of a specified pixel in this bitmap.

FUNCTION SetPixel (BYVAL x AS LONG, BYVAL y AS LONG, BYVAL colour AS ARGB) AS GpStatus

Return value

If the function succeeds, it returns StatusOk, which is an element of the GpStatus enumeration.

If the function fails, it returns one of the other elements of the GpStatus enumeration.

Remarks

Depending on the format of the bitmap, GetPixel might not return the same value as was set by SetPixel. For example, if you call SetPixel on a Bitmap object whose pixel format is 32bppPARGB, the RGB components are premultiplied. A subsequent call to GetPixel might return a different value because of rounding. Also, if you call SetPixel on a Bitmap whose color depth is 16 bits per pixel, information could be lost in the conversion from 32 to 16 bits, and a subsequent call to GetPixel return a different value.

Flat API function: GdipBitmapSetPixel

Example

' ========================================================================================
' The following example creates a Bitmap object based on a JPEG file. The code draws the
' bitmap once unaltered. Then the code calls the SetPixel method to create a
' checkered pattern of black pixels in the bitmap and draws the altered bitmap.
' ========================================================================================
SUB Example_SetPixel (BYVAL hdc AS HDC)

   ' // Create a graphics object from the window device context
   DIM graphics AS CGpGraphics = hdc
   ' // Set the scaling factors using the DPI ratios
   graphics.ScaleTransformForDpi

   ' // Create a Bitmap object from a JPEG file.
   DIM myBitmap AS CGpBitmap = "climber.jpg"
   ' // Set the resolution of the image using the DPI ratios
   myBitmap.SetResolutionForDpi

   '// Draw the bitmap
   graphics.DrawImage(@myBitmap, 10, 10)

   ' // Get the width and height of the bitmap
   DIM nWidth AS DWORD = myBitmap.GetWidth
   DIM nHeight AS DWORD = myBitmap.GetHeight

   ' // Make a checkered pattern of black pixels
   FOR row AS LONG = 0 TO nWidth - 1 STEP 2
      FOR col AS LONG = 0 TO nHeight STEP 2
         myBitmap.SetPixel(row, col, ARGB_BLACK)
      NEXT
   NEXT

   ' // Draw the altered bitmap.
   graphics.DrawImage(@myBitmap, 200, 10)

END SUB
' ========================================================================================

SetResolution (CGpBitmap)

Sets the resolution of this Bitmap object.

FUNCTION SetResolution (BYVAL xdpi AS SINGLE, BYVAL ydpi AS SINGLE) AS GpStatus

Return value

If the function succeeds, it returns StatusOk, which is an element of the GpStatus enumeration.

If the function fails, it returns one of the other elements of the GpStatus enumeration.

Flat API function: GdipBitmapSetResolution

Usage example

   ' // Create a graphics object from the window device context
   DIM graphics AS CGpGraphics = hdc
   ' // Get the DPI scaling ratios
   DIM rxRatio AS SINGLE = graphics.GetDpiX / 96
   DIM ryRatio AS SINGLE = graphics.GetDpiY / 96
   ' // Set the scale transform
   graphics.ScaleTransform(rxRatio, ryRatio)

   ' // Create a Bitmap object from a JPEG file.
   DIM bmp AS CGpBitmap = "climber.jpg"
   ' // Set the resolution of the image using the DPI ratios
   bmp.SetResolution(rxRatio, ryRatio)

SetResolutionForDpi (CGpBitmap)

Sets the resolution of this Bitmap object. Uses the current DPI seetings to set the horizontal and vertical resolution in dots per inch.

FUNCTION SetResolutionForDpi () AS GpStatus

Return value

If the function succeeds, it returns StatusOk, which is an element of the GpStatus enumeration.

If the function fails, it returns one of the other elements of the GpStatus enumeration.

Flat API function: GdipBitmapSetResolution

Usage example

   ' // Create a graphics object from the window device context
   DIM graphics AS CGpGraphics = hdc
   ' // Set the scale transform using the DPI settings
   graphics.ScaleTransformForDpi

   ' // Create a Bitmap object from a JPEG file.
   DIM bmp AS CGpBitmap = "climber.jpg"
   ' // Set the resolution of the image using the DPI settings
   bmp.SetResolutionForDpi

UnlockBits (CGpBitmap)

Unlocks a portion of this bitmap that was previously locked by a call to LockBits.

FUNCTION UnlockBits (BYVAL lockedBitmapData AS BitmapData PTR) AS GpStatus

Return value

If the function succeeds, it returns StatusOk, which is an element of the GpStatus enumeration.

If the function fails, it returns one of the other elements of the GpStatus enumeration.

Remarks

LockBits and UnlockBits must be used as a pair. A call to the LockBits method of a Bitmap object establishes a temporary buffer that you can use to read or write pixel data in a specified format. After you write to the temporary buffer, a call to UnlockBits copies the pixel data in the buffer to the Bitmap object. If the pixel format of the temporary buffer is different from the pixel format of the Bitmap object, the pixel data is converted appropriately.

Flat API function: GdipBitmapUnlockBits

Example

' ========================================================================================
' Demonstrates the use of GdipBitmapLockBits/GdipBitmapUnlockBits.
' This example inverts the colors of a Bitmap.
' ========================================================================================
SUB Example_LockBits (BYVAL hdc AS HDC)

   ' // Create a graphics object from the window device context
   DIM graphics AS CGpGraphics = hdc
   ' // Set the scaling factors using the DPI ratios
   graphics.ScaleTransformForDpi

   ' // Create a Bitmap object from a JPEG file.
   DIM bmp AS CGpBitmap = "climber.jpg"
   ' // Set the resolution of the image using the DPI ratios
   bmp.SetResolutionForDpi

   ' // Get the width and height of the bitmap
   DIM nWidth AS DWORD = bmp.GetWidth
   DIM nHeight AS DWORD = bmp.GetHeight

   ' // Define lock rectangle
   DIM rc AS GpRect = (0, 0, nWidth, nHeight)

   ' // Lock bitmap bits
   DIM bmpData AS BitmapData
   bmp.LockBits(@rc, ImageLockModeRead OR ImageLockModeWrite, PixelFormat32bppARGB, @bmpData)
   ' // Alternate way
   ' DIM bmpData AS BitmapData = bmp.LockBits(@rc, ImageLockModeRead OR ImageLockModeWrite, PixelFormat32bppARGB)

   ' // Invert colors
   DIM pPixels AS UBYTE PTR = bmpData.Scan0
   FOR y AS LONG = 0 TO nHeight - 1
      FOR x AS LONG = 0 TO nWidth - 1
         DIM offset AS LONG = y * bmpData.Stride + x * 4
         pPixels[offset + 0] = 255 - pPixels[offset + 0] ' Blue
         pPixels[offset + 1] = 255 - pPixels[offset + 1] ' Green
         pPixels[offset + 2] = 255 - pPixels[offset + 2] ' Red
         ' Alpha remains unchanged
      NEXT
   NEXT

   ' // Unlock bitmap bits
   bmp.UnlockBits(@bmpData)

   ' // Draw the modified bitmap.
   graphics.DrawImage(@bmp, 10, 10)

END SUB
' ========================================================================================

Constructors (CGpMetafile)

Creates a Windows GDI+ Metafile object for playback based on a Windows Graphics Device Interface (GDI) Enhanced Metafile (EMF) file.

CONSTRUCTOR CGpMetafile (BYVAL hEmf AS HENHMETAFILE, BYVAL deleteEmf AS BOOL = FALSE)

Creates a Metafile object from an IStream interface for playback.

CONSTRUCTOR CGpMetafile (BYVAL pStream AS IStream PTR)

Creates a Metafile object for playback.

CONSTRUCTOR CGpMetafile (BYVAL pwszFileName AS WSTRING PTR)
CONSTRUCTOR CGpMetafile (BYVAL pwszFileName AS WSTRING PTR, BYVAL wmfPFH AS WmfPlaceableFileHeader PTR)
CONSTRUCTOR CGpMetafile (BYVAL hWmf AS HMETAFILE, BYVAL wmfPFH AS WmfPlaceableFileHeader PTR, _
   BYVAL deleteWmf AS BOOL = FALSE)

Creates a Metafile object for recording.

CONSTRUCTOR CGpMetafile (BYVAL referenceHdc AS HDC, BYVAL nType AS EmfType = EmfTypeEmfPlusDual, _
   BYVAL description AS WSTRING PTR = NULL)
CONSTRUCTOR CGpMetafile (BYVAL referenceHdc AS HDC, BYVAL frmRect AS GpRectF PTR, _
   BYVAL frameUnit AS MetafileFrameUnit = MetafileFrameUnitGdi, _
   BYVAL nType AS EmfType = EmfTypeEmfPlusDual, BYVAL description AS WSTRING PTR = NULL)
CONSTRUCTOR CGpMetafile (BYVAL referenceHdc AS HDC, BYVAL frmRect AS GpRect PTR, _
   BYVAL frameUnit AS MetafileFrameUnit = MetafileFrameUnitGdi, _
   BYVAL nType AS EmfType = EmfTypeEmfPlusDual, BYVAL description AS WSTRING PTR = NULL)

Creates a Metafile object for recording.

CONSTRUCTOR CGpMetafile (BYVAL pwszFileName AS WSTRING PTR, BYVAL referenceHdc AS HDC, _
   BYVAL nType AS EmfType = EmfTypeEmfPlusDual, BYVAL description AS WSTRING PTR = NULL)
CONSTRUCTOR CGpMetafile (BYVAL pwszFileName AS WSTRING PTR, BYVAL referenceHdc AS HDC, _
   BYVAL frmRect AS GpRectF PTR, BYVAL frameUnit AS MetafileFrameUnit = MetafileFrameUnitGdi, _
   BYVAL nType AS EmfType = EmfTypeEmfPlusDual, BYVAL description AS WSTRING PTR = NULL)
CONSTRUCTOR CGpMetafile (BYVAL pwszFileName AS WSTRING PTR, BYVAL referenceHdc AS HDC, _
   BYVAL frmRect AS GpRect PTR, BYVAL frameUnit AS MetafileFrameUnit = MetafileFrameUnitGdi, _
   BYVAL nType AS EmfType = EmfTypeEmfPlusDual, BYVAL description AS WSTRING PTR = NULL)

Creates a Metafile object from an IStream interface for recording.

CONSTRUCTOR CGpMetafile (BYVAL pStream AS IStream PTR, BYVAL referenceHdc AS HDC, _
   BYVAL nType AS EmfType, BYVAL description AS WSTRING PTR)
CONSTRUCTOR CGpMetafile (BYVAL pStream AS IStream PTR, BYVAL referenceHdc AS HDC, _
   BYVAL frmRect AS GpRectF PTR, BYVAL frameUnit AS MetafileFrameUnit = MetafileFrameUnitGdi, _
   BYVAL nType AS EmfType, BYVAL description AS WSTRING PTR)
CONSTRUCTOR CGpMetafile (BYVAL pStream AS IStream PTR, BYVAL referenceHdc AS HDC, _
   BYVAL frmRect AS GpRect PTR, BYVAL frameUnit AS MetafileFrameUnit = MetafileFrameUnitGdi, _
   BYVAL nType AS EmfType, BYVAL description AS WSTRING PTR)

Remarks

When recording to a file, the file must be writable, and Windows GDI+ must be able to obtain an exclusive lock on the file.

EmfToWmfBits (CGpMetafile)

Converts an enhanced-format metafile to a Windows Metafile Format (WMF) metafile and stores the converted records in a specified buffer.

FUNCTION EmfToWmfBits (BYVAL hEmf AS HENHMETAFILE, BYVAL cbData16 AS UINT, BYVAL pData16 AS BYTE PTR, _
   BYVAL iMapMode AS INT_ = MM_ANISOTROPIC, BYVAL eFlags AS INT_ = EmfToWmfBitsFlagsDefault) AS GpStatus

Return value

If the function succeeds, it returns StatusOk, which is an element of the GpStatus enumeration.

If the function fails, it returns one of the other elements of the GpStatus enumeration.

Remarks

This method replaces the records originally in the Metafile object with the converted records. To retain a copy of the original Metafile object, call the Clone method.

If you set the emfType parameter to EmfTypeEmfPlusDual, the converted metafile contains an Enhanced Metafile (EMF) representation and an EMF+ representation. The EMF representation is the original set of EMF records rather than EMF records converted back from the newly created EMF+ records.

It is possible for the return value to be StatusOk and the value returned in conversionSuccess to be FALSE. Sometimes the overall conversion is considered to be successful even if a few individual records failed to convert with complete accuracy. For example, the original metafile might have records or operations that are not supported by Windows GDI+ (or EMF+), in which case those records or operations are emulated.

GetDownLevelRasterizationLimit (CGpMetafile)

Gets the rasterization limit currently set for this metafile. The rasterization limit is the resolution used for certain brush bitmaps that are stored in the metafile. For a detailed explanation of the rasterization limit, see SetDownLevelRasterizationLimit.

FUNCTION GetDownLevelRasterizationLimit () AS UINT

Return value

This method returns the rasterization limit in dpi.

GetHENHMETAFILE (CGpMetafile)

Gets a Windows handle to an Enhanced Metafile (EMF) file.

FUNCTION GetHENHMETAFILE () AS HENHMETAFILE

Return value

This method sets the Metafile object to an invalid state. The user is responsible for calling DeleteEnhMetafile, to delete the Windows handle.

GetMetafileHeader (CGpMetafile)

Gets the metafile header of this metafile.

FUNCTION GetMetafileHeader (BYVAL mh AS MetafileHeader PTR) AS GpStatus
FUNCTION GetMetafileHeader (BYVAL hEmf AS HENHMETAFILE, BYVAL mh AS MetafileHeader PTR) AS GpStatus
FUNCTION GetMetafileHeader (BYVAL hWmf AS HMETAFILE, BYVAL mh AS MetafileHeader PTR) AS GpStatus
FUNCTION GetMetafileHeader (BYVAL pwsFileName AS WSTRING PTR, BYVAL mh AS MetafileHeader PTR) AS GpStatus
FUNCTION GetMetafileHeader (BYVAL pStream AS IStream PTR, BYVAL mh AS MetafileHeader PTR) AS GpStatus

Return value

If the function succeeds, it returns StatusOk, which is an element of the GpStatus enumeration.

If the function fails, it returns one of the other elements of the GpStatus enumeration.

PlayRecord (CGpMetafile)

Plays a metafile record.

FUNCTION PlayRecord (BYVAL recordType AS EmfPlusRecordType, BYVAL flags AS UINT, _
   BYVAL dataSize AS UINT, BYVAL pData AS BYTE PTR) AS GpStatus

Return value

If the function succeeds, it returns StatusOk, which is an element of the GpStatus enumeration.

If the function fails, it returns one of the other elements of the GpStatus enumeration.

SetDownLevelRasterizationLimit (CGpMetafile)

Sets the resolution for certain brush bitmaps that are stored in this metafile.

FUNCTION SetDownLevelRasterizationLimit (BYVAL metafileRasterizationLimitDpi AS UINT) AS GpStatus

Return value

If the function succeeds, it returns StatusOk, which is an element of the GpStatus enumeration.

If the function fails, it returns one of the other elements of the GpStatus enumeration.

Remarks

The purpose of this method is to prevent metafiles from becoming too large as a result of texture and gradient brushes being stored at high resolution. Suppose you construct a Metafile object (for recording an EmfTypeEmfOnly metafile) based on the device context of a printer that has a resolution of 600 dpi. Also suppose you create a path gradient brush or a texture brush based on a Bitmap object that has a resolution of 96 dpi. If the bitmap that represents that brush is stored in the metafile with a resolution of 96 dpi, it will require much less space than if it is stored with a resolution of 600 dpi.

The default rasterization limit for metafiles is 96 dpi. So if you do not call this method at all, path gradient brush and texture brush bitmaps are stored with a resolution of 96 dpi.

The rasterization limit has an effect on metafiles of type EmfTypeEmfOnly and EmfTypeEmfPlusDual, but it has no effect on metafiles of type EmfTypeEmfPlusOnly.

Constructor (CGpCachedBitmap)

Creates a CachedBitmap object based on a Bitmap object and a Graphics object. The cached bitmap takes the pixel data from the Bitmap object and stores it in a format that is optimized for the display device associated with the Graphics object.

CONSTRUCTOR CGpCachedBitmap (BYVAL pBitmap AS CGpBitmap PTR, BYVAL pGraphics AS CGpGraphics PTR)

Remarks

You can display a cached bitmap by passing the address of a CachedBitmap object to the DrawCachedBitmap method of a Graphics object. Use the Graphics object that was passed to the CachedBitmap constructor or another Graphics object that represents the same device.

Example

' ========================================================================================
' The following example creates a CachedBitmap object based on a Bitmap object and a
' Graphics object. The code calls the DrawCachedBitmap method of that Graphics object
' to display the cached bitmap.
' ========================================================================================
SUB Example_CachedBitmap (BYVAL hdc AS HDC)

   ' // Create a graphics object from the window device context
   DIM graphics AS CGpGraphics = hdc

   ' // Get the DPI scaling ratios
   DIM rxRatio AS SINGLE = graphics.GetDpiX / 96
   DIM ryRatio AS SINGLE = graphics.GetDpiY / 96
   ' ScaleTransform can't be used with cached bitmaps, that can't be resized

   ' // Load the image
   DIM myBitmap AS CGpBitmap = "Climber.jpg"

   ' // Create a cached bitmap
   DIM cachedBitmap AS CGpCachedBitmap = CGpCachedBitmap(@myBitmap, @graphics)

   ' // Draw the cached bitmap
   graphics.DrawCachedBitmap(@cachedBitmap, 10 * rxRatio, 10 * ryRatio)

END SUB
' ========================================================================================

Constructor (CGpImageAttributes)

Creates a new ImageAttributes object. This constructor is the default constructor and has no parameters.

CONSTRUCTOR CGpImageAttributes

Creates and initializes an ImageAttributes object from another ImageAttributes object.

Flat API function: GdipCreateImageAttributes.

CONSTRUCTOR CGpImageAttributes (BYVAL pImgAttr AS CGpImageAttributes PTR)

Flat API function: GdipCloneImageAttributes.

Example

' ========================================================================================
' This example clones an ImageAttributes object and applies different effects to each.
' ========================================================================================
SUB Example_CloneImageAttributes (BYVAL hdc AS HDC)

   ' Create graphics object
   DIM graphics AS CGpGraphics = hdc
   graphics.ScaleTransformForDpi

   ' Load image
   DIM image AS CGpBitmap = "climber.jpg"
   image.SetResolutionForDpi

   ' Get image dimensions
   DIM nWidth AS UINT = image.GetWidth
   DIM nHeight AS UINT = image.GetHeight

   ' Create original ImageAttributes and apply grayscale matrix
   DIM imgAttrOriginal AS CGpImageAttributes
   DIM grayMatrix AS ColorMatrix
   grayMatrix.m(0,0) = 0.3 : grayMatrix.m(0,1) = 0.3 : grayMatrix.m(0,2) = 0.3
   grayMatrix.m(1,0) = 0.59: grayMatrix.m(1,1) = 0.59: grayMatrix.m(1,2) = 0.59
   grayMatrix.m(2,0) = 0.11: grayMatrix.m(2,1) = 0.11: grayMatrix.m(2,2) = 0.11
   grayMatrix.m(3,3) = 1
   grayMatrix.m(4,4) = 1
   imgAttrOriginal.SetColorMatrix(@grayMatrix)

   ' Clone the ImageAttributes object
   DIM imgAttrClone AS CGpImageAttributes = @imgAttrOriginal

   ' Apply gamma correction to the clone
   imgAttrClone.SetGamma(0.6)

   ' Draw original image (no effect)
   graphics.DrawImage(@image, 10, 10, nWidth, nHeight)

   ' Draw grayscale image (original attributes)
   DIM rcGray AS GpRect = (210, 10, nWidth, nHeight)
   graphics.DrawImage(@image, @rcGray, 0, 0, nWidth, nHeight, UnitPixel, @imgAttrOriginal)

   ' Draw grayscale + gamma image (cloned and modified)
   DIM rcClone AS GpRect = (10, 150, nWidth, nHeight)
   graphics.DrawImage(@image, @rcClone, 0, 0, nWidth, nHeight, UnitPixel, @imgAttrClone)

END SUB
' ========================================================================================

ClearBrushRemapTable (CGpImageAttributes)

Clears the brush color-remap table of this ImageAttributes object.

FUNCTION ClearBrushRemapTable () AS GpStatus

Return value

If the function succeeds, it returns StatusOk, which is an element of the GpStatus enumeration.

If the function fails, it returns one of the other elements of the GpStatus enumeration.

Flat API function: GdipSetImageAttributesRemapTable.

ClearColorKey (CGpImageAttributes)

Clears the color key (transparency range) for a specified category.

FUNCTION ClearColorKey (BYVAL nType AS ColorAdjustType = ColorAdjustTypeDefault) AS GpStatus

Remarks

An ImageAttributes object maintains color and grayscale settings for five adjustment categories: default, bitmap, brush, pen, and text. For example, you can specify one color key for the default category, a different color key for the bitmap category, and still a different color key for the pen category.

The default color- and grayscale-adjustment settings apply to all categories that don’t have adjustment settings of their own. For example, if you never specify any adjustment settings for the pen category, then the default settings apply to the pen category.

As soon as you specify a color- or grayscale-adjustment setting for a certain category, the default adjustment settings no longer apply to that category. For example, suppose you specify a default color key that makes any color with a red component from 200 through 255 transparent and you specify a default gamma value of 1.8. If you set the color key of the pen category by calling SetColorKey, then the default color key and the default gamma value will not apply to pens. If you later clear the pen color key by calling ClearColorKey, the pen category will not revert to the default color key; rather, the pen category will have no color key. Similarly, the pen category will not revert to the default gamma value; rather, the pen category will have no gamma value.

Return value

If the function succeeds, it returns StatusOk, which is an element of the GpStatus enumeration.

If the function fails, it returns one of the other elements of the GpStatus enumeration.

Flat API function: GdipSetImageAttributesColorKeys.

ClearColorMatrices (CGpImageAttributes)

Clears the color-adjustment matrix and the grayscale-adjustment matrix for a specified category.

FUNCTION ClearColorMatrices (BYVAL nType AS ColorAdjustType = ColorAdjustTypeDefault) AS GpStatus

Return value

If the function succeeds, it returns StatusOk, which is an element of the GpStatus enumeration.

If the function fails, it returns one of the other elements of the GpStatus enumeration.

Remarks

An ImageAttributes object maintains color and grayscale settings for five adjustment categories: default, bitmap, brush, pen, and text. For example, you can specify a pair (color and grayscale) of adjustment matrices for the default category, a different pair of adjustment matrices for the bitmap category, and still a different pair of adjustment matrices for the pen category.

The default color- and grayscale-adjustment settings apply to all categories that don’t have adjustment settings of their own. For example, if you never specify any adjustment settings for the pen category, then the default settings apply to the pen category.

As soon as you specify a color- or grayscale-adjustment setting for a certain category, the default adjustment settings no longer apply to that category. For example, suppose you specify a pair (color and grayscale) of adjustment matrices and a gamma value for the default category. If you set a pair of adjustment matrices for the pen category by calling SetColorMatrices, then the default adjustment matrices will not apply to pens. If you later clear the pen adjustment matrices by calling ClearColorMatrices, the pen category will not revert to the default adjustment matrices; rather, the pen category will have no adjustment matrices. Similarly, the pen category will not revert to the default gamma value; rather, the pen category will have no gamma value.

Flat API function: GdipSetImageAttributesColorMatrix.

ClearColorMatrix (CGpImageAttributes)

Clears the color-adjustment matrix for a specified category.

FUNCTION ClearColorMatrix (BYVAL nType AS ColorAdjustType = ColorAdjustTypeDefault) AS GpStatus

Return value

If the function succeeds, it returns StatusOk, which is an element of the GpStatus enumeration.

If the function fails, it returns one of the other elements of the GpStatus enumeration.

Remarks

An ImageAttributes object maintains color and grayscale settings for five adjustment categories: default, bitmap, brush, pen, and text. For example, you can specify a color-adjustment matrix for the default category, a different color-adjustment matrix for the bitmap category, and still a different color-adjustment matrix for the pen category.

The default color- and grayscale-adjustment settings apply to all categories that don’t have adjustment settings of their own. For example, if you never specify any adjustment settings for the pen category, then the default settings apply to the pen category.

As soon as you specify a color- or grayscale-adjustment setting for a certain category, the default adjustment settings no longer apply to that category. For example, suppose you specify a color-adjustment matrix and a gamma value for the default category. If you set a color-adjustment matrix for the pen category by calling SetColorMatrix, then the default color-adjustment matrix will not apply to pens. If you later clear the pen color-adjustment matrix by calling ClearColorMatrix, the pen category will not revert to the default adjustment matrix; rather, the pen category will have no adjustment matrix. Similarly, the pen category will not revert to the default gamma value; rather, the pen category will have no gamma value.

Flat API function: GdipSetImageAttributesColorMatrix.

ClearGamma (CGpImageAttributes)

Disables gamma correction for a specified category.

FUNCTION ClearGamma (BYVAL nType AS ColorAdjustType = ColorAdjustTypeDefault) AS GpStatus

Return value

If the function succeeds, it returns StatusOk, which is an element of the GpStatus enumeration.

If the function fails, it returns one of the other elements of the GpStatus enumeration.

Remarks

An ImageAttributes object maintains color and grayscale settings for five adjustment categories: default, bitmap, brush, pen, and text. For example, you can specify a gamma value for the default category, a different gamma value for the bitmap category, and still a different gamma value for the pen category.

The default color- and grayscale-adjustment settings apply to all categories that don’t have adjustment settings of their own. For example, if you never specify any adjustment settings for the pen category, then the default settings apply to the pen category.

As soon as you specify a color- or grayscale-adjustment setting for a certain category, the default adjustment settings no longer apply to that category. For example, suppose you specify a gamma value and a color-adjustment matrix for the default category. If you set the gamma value for the pen category by calling SetGamma, then the default gamma value will not apply to pens. If you later clear the pen gamma value by calling ClearGamma, the pen category will not revert to the default gamma value; rather, the pen category will have no gamma value. Similarly, the pen category will not revert to the default color-adjustment matrix; rather, the pen category will have no color-adjustment matrix.

Flat API function: GdipSetImageAttributesGamma.

ClearNoOp (CGpImageAttributes)

Clears the NoOp setting for a specified category.

FUNCTION ClearNoOp (BYVAL nType AS ColorAdjustType = ColorAdjustTypeDefault) AS GpStatus

Return value

If the function succeeds, it returns StatusOk, which is an element of the GpStatus enumeration.

If the function fails, it returns one of the other elements of the GpStatus enumeration.

Remarks

You can disable color adjustment for a certain object type by calling the SetNoOp method. Later, you can reinstate color adjustment for that object type by calling the ClearNoOp method. For example, the following statement disables color adjustment for brushes:

myImageAttributes.SetNoOp(ColorAdjustTypeBrush)

The following statement reinstates the brush color adjustment that was in place before the call to SetNoOp:

myImageAttributes.ClearNoOp(ColorAdjustTypeBrush)

Flat API function: GdipSetImageAttributesNoOp.

ClearOutputChannel (CGpImageAttributes)

Clears the cyan-magenta-yellow-black (CMYK) output channel setting for a specified category.

FUNCTION ClearOutputChannel (BYVAL nType AS ColorAdjustType = ColorAdjustTypeDefault) AS GpStatus

Return value

If the function succeeds, it returns StatusOk, which is an element of the GpStatus enumeration.

If the function fails, it returns one of the other elements of the GpStatus enumeration.

Remarks

An ImageAttributes object maintains color and grayscale settings for five adjustment categories: default, bitmap, brush, pen, and text. For example, you can specify an output channel for the default category and a different output channel for the bitmap category.

The default color- and grayscale-adjustment settings apply to all categories that don’t have adjustment settings of their own. For example, if you never specify any adjustment settings for the bitmap category, then the default settings apply to the bitmap category.

As soon as you specify a color- or grayscale-adjustment setting for a certain category, the default adjustment settings no longer apply to that category. For example, suppose you specify an output channel and an adjustment matrix for the default category. If you set the output channel for the bitmap category by calling SetOutputChannel, then the default output channel will not apply to bitmaps. If you later clear the bitmap output channel by calling ClearOutputChannel, the bitmap category will not revert to the default output channel; rather, the bitmap category will have no output channel setting. Similarly, the bitmap category will not revert to the default color-adjustment matrix; rather, the bitmap category will have no color-adjustment matrix.

Flat API function: GdipSetImageAttributesOutputChannel.

ClearOutputChannelColorProfile (CGpImageAttributes)

Clears the output channel color profile setting for a specified category.

FUNCTION ClearOutputChannelColorProfile (BYVAL nType AS ColorAdjustType = ColorAdjustTypeDefault) AS GpStatus

Return value

If the function succeeds, it returns StatusOk, which is an element of the GpStatus enumeration.

If the function fails, it returns one of the other elements of the GpStatus enumeration.

Remarks

An ImageAttributes object maintains color and grayscale settings for five adjustment categories: default, bitmap, brush, pen, and text. For example, you can specify an output channel profile for the default category and a different output channel profile for the bitmap category.

The default color- and grayscale-adjustment settings apply to all categories that don’t have adjustment settings of their own. For example, if you never specify any adjustment settings for the bitmap category, then the default settings apply to the bitmap category.

As soon as you specify a color- or grayscale-adjustment setting for a certain category, the default adjustment settings no longer apply to that category. For example, suppose you specify an output channel profile and an adjustment matrix for the default category. If you set the output channel profile for the bitmap category by calling SetOutputChannelColorProfile, then the default output channel profile will not apply to bitmaps. If you later clear the bitmap output channel profile by calling ClearOutputChannelColorProfile, the bitmap category will not revert to the default output channel profile; rather, the bitmap category will have no output channel profile setting. Similarly, the bitmap category will not revert to the default color-adjustment matrix; rather, the bitmap category will have no color-adjustment matrix.

Flat API function: GdipSetImageAttributesOutputChannelColorProfile.

ClearRemapTable (CGpImageAttributes)

Clears the color-remap table for a specified category.

FUNCTION ClearRemapTable (BYVAL nType AS ColorAdjustType = ColorAdjustTypeDefault) AS GpStatus

Return value

If the function succeeds, it returns StatusOk, which is an element of the GpStatus enumeration.

If the function fails, it returns one of the other elements of the GpStatus enumeration.

Remarks

An ImageAttributes object maintains color and grayscale settings for five adjustment categories: default, bitmap, brush, pen, and text. For example, you can specify a remap table for the default category, a different remap table for the bitmap category, and still a different remap table for the pen category.

The default color- and grayscale-adjustment settings apply to all categories that don’t have adjustment settings of their own. For example, if you never specify any adjustment settings for the pen category, then the default settings apply to the pen category.

As soon as you specify a color- or grayscale-adjustment setting for a certain category, the default adjustment settings no longer apply to that category. For example, suppose you specify a remap table and a gamma value for the default category. If you set the remap table for the pen category by calling SetRemapTable, then the default remap table will not apply to pens. If you later clear the pen remap table by calling ClearRemapTable, the pen category will not revert to the default remap table; rather, the pen category will have no remap table. Similarly, the pen category will not revert to the default gamma value; rather, the pen category will have no gamma value.

Flat API function: GdipSetImageAttributesRemapTable.

Example

' ========================================================================================
' This example shows and image, applies a color-remap table and shows he remaped image,
' clears the color-remap table and displays the image again.
' ========================================================================================
SUB Example_ClearRemapTable (BYVAL hdc AS HDC)

   ' // Create a graphics object from the window device context
   DIM graphics AS CGpGraphics = hdc
   ' // Set the scaling factors using the DPI ratios
   graphics.ScaleTransformForDpi

   DIM image AS CGpBitmap = "RedGreenStripes.bmp"
   image.SetResolutionForDpi

   ' // Get the width and height of the image
   DIM nWidth AS UINT = image.GetWidth
   DIM nHeight AS UINT = image.GetHeight

   ' // Create an ImageAttributes object
   DIM imgAttr AS CGpImageAttributes

   ' // Draw the original
   DIM rc AS GpRect = (10, 10, nWidth, nHeight)
   graphics.DrawImage(@image, @rc, 0, 0, nWidth, nHeight, UnitPixel, @imgAttr)

   ' // Create a remap table that converts red to blue.
   DIM map AS GpColorMap
   map.oldColor = ARGB_RED
   map.newColor = ARGB_BLUE

   ' // Set  bitmap remap table of the image attributes object
   imgAttr.SetRemapTable(1, @map)

   ' // Draw the image with remap applied
   rc = TYPE<GpRect>(100, 10, nWidth, nHeight)
   graphics.DrawImage(@image, @rc, 0, 0, nWidth, nHeight, UnitPixel, @imgAttr)

   ' // Clears the color-remap table
   imgAttr.ClearRemapTable
   
   ' // Draw image again (should appear unaltered)
   rc = TYPE<GpRect>(190, 10, nWidth, nHeight)
   graphics.DrawImage(@image, @rc, 0, 0, nWidth, nHeight, UnitPixel, @imgAttr)

END SUB
' ========================================================================================

ClearThreshold (CGpImageAttributes)

Clears the threshold value for a specified category.

FUNCTION ClearThreshold (BYVAL nType AS ColorAdjustType = ColorAdjustTypeDefault) AS GpStatus

Return value

If the function succeeds, it returns StatusOk, which is an element of the GpStatus enumeration.

If the function fails, it returns one of the other elements of the GpStatus enumeration.

Remarks

The threshold is a value from 0 through 1 that specifies a cutoff point for each color component. For example, suppose the threshold is set to 0.7, and suppose you are rendering a color whose red, green, and blue components are 230, 50, and 220. The red component, 230, is greater than 0.7×255, so the red component will be changed to 255 (full intensity). The green component, 50, is less than 0.7×255, so the green component will be changed to 0. The blue component, 220, is greater than 0.7×255, so the blue component will be changed to 255.

An ImageAttributes object maintains color and grayscale settings for five adjustment categories: default, bitmap, brush, pen, and text. For example, you can specify a threshold for the default category, a different threshold for the bitmap category, and still a different threshold for the pen category.

The default color- and grayscale-adjustment settings apply to all categories that don’t have adjustment settings of their own. For example, if you never specify any adjustment settings for the pen category, then the default settings apply to the pen category.

As soon as you specify a color- or grayscale-adjustment setting for a certain category, the default adjustment settings no longer apply to that category. For example, suppose you specify a threshold and a gamma value for the default category. If you set the threshold for the pen category by calling SetThreshold, then the default threshold will not apply to pens. If you later clear the pen threshold by calling ClearThreshold, the pen category will not revert to the default threshold; rather, the pen category will have no threshold. Similarly, the pen category will not revert to the default gamma value; rather, the pen category will have no gamma value.

Flat API function: GdipSetImageAttributesThreshold.

Clone (CGpImageAttributes)

Copies the contents of the existing ImageAttributes object into a new ImageAttributes object.

FUNCTION Clone (BYVAL pCloneImgAttr AS CGpImageAttributes PTR) AS GpStatus

Return value

If the function succeeds, it returns StatusOk, which is an element of the GpStatus enumeration.

If the function fails, it returns one of the other elements of the GpStatus enumeration.

Flat API function: GdipCloneImageAttributes.

Example

' ========================================================================================
' This example clones an ImageAttributes object and applies different effects to each.
' ========================================================================================
SUB Example_CloneImageAttributes (BYVAL hdc AS HDC)

   ' Create graphics object
   DIM graphics AS CGpGraphics = hdc
   graphics.ScaleTransformForDpi

   ' Load image
   DIM image AS CGpBitmap = "climber.jpg"
   image.SetResolutionForDpi

   ' Get image dimensions
   DIM nWidth AS UINT = image.GetWidth
   DIM nHeight AS UINT = image.GetHeight

   ' Create original ImageAttributes and apply grayscale matrix
   DIM imgAttrOriginal AS CGpImageAttributes
   DIM grayMatrix AS ColorMatrix
   grayMatrix.m(0,0) = 0.3 : grayMatrix.m(0,1) = 0.3 : grayMatrix.m(0,2) = 0.3
   grayMatrix.m(1,0) = 0.59: grayMatrix.m(1,1) = 0.59: grayMatrix.m(1,2) = 0.59
   grayMatrix.m(2,0) = 0.11: grayMatrix.m(2,1) = 0.11: grayMatrix.m(2,2) = 0.11
   grayMatrix.m(3,3) = 1
   grayMatrix.m(4,4) = 1
   imgAttrOriginal.SetColorMatrix(@grayMatrix)

   ' Clone the ImageAttributes object
   DIM imgAttrClone AS CGpImageAttributes
   imgAttrOriginal.Clone(@imgAttrClone)

   ' Apply gamma correction to the clone
   imgAttrClone.SetGamma(0.6)

   ' Draw original image (no effect)
   graphics.DrawImage(@image, 10, 10, nWidth, nHeight)

   ' Draw grayscale image (original attributes)
   DIM rcGray AS GpRect = (210, 10, nWidth, nHeight)
   graphics.DrawImage(@image, @rcGray, 0, 0, nWidth, nHeight, UnitPixel, @imgAttrOriginal)

   ' Draw grayscale + gamma image (cloned and modified)
   DIM rcClone AS GpRect = (10, 150, nWidth, nHeight)
   graphics.DrawImage(@image, @rcClone, 0, 0, nWidth, nHeight, UnitPixel, @imgAttrClone)

END SUB
' ========================================================================================

GetAdjustedPalette (CGpImageAttributes)

Adjusts the colors in a palette according to the adjustment settings of a specified category.

FUNCTION GetAdjustedPalette (BYVAL pColorPalette AS ColorPalette PTR, BYVAL colorAdjustType AS LONG) AS GpStatus

Return value

If the function succeeds, it returns StatusOk, which is an element of the GpStatus enumeration.

If the function fails, it returns one of the other elements of the GpStatus enumeration.

Remarks

An ImageAttributes object maintains color and grayscale settings for five adjustment categories: default, bitmap, brush, pen, and text. For example, you can specify a color-remap table for the default category, a different color-remap table for the bitmap category, and still a different color-remap table for the pen category.

When you call GetAdjustedPalette, you can specify the adjustment category that is used to adjust the palette colors. For example, if you pass ColorAdjustTypeBitmap to the GetAdjustedPalette method, then the adjustment settings of the bitmap category are used to adjust the palette colors.

Flat API function: GdipGetImageAttributesAdjustedPalette.

Example

' ========================================================================================
' The following example initializes a ColorPalette structure with four colors: aqua, black,
' red, and green. The code also creates an ImageAttributes object and sets its bitmap remap
' table so that green will be converted to blue. Then the code adjusts the palette colors by
' passing the address of the palette to the GdipGetAdjustedPalette function. The code displays
' the four palette colors twice: once before the adjustment and once after the adjustment.
' ========================================================================================
SUB Example_GetAdjustedPalette (BYVAL hdc AS HDC)

   ' // Create a graphics object from the window device context
   DIM graphics AS CGpGraphics = hdc
   ' // Set the scaling factors using the DPI ratios
   graphics.ScaleTransformForDpi

   ' // Create a palette that has four entries.
   DIM clrPalette AS COLORPALETTE PTR
   DIM PALETTE_SIZE AS LONG = 4
   clrPalette = Allocate(SIZEOF(COLORPALETTE) + PALETTE_SIZE * SIZEOF(ARGB))
   clrPalette->Flags = 0
   clrPalette->Count = PALETTE_SIZE

   clrPalette->Entries(0) = ARGB_Aqua
   clrPalette->Entries(1) = ARGB_Black
   clrPalette->Entries(2) = ARGB_Red
   clrPalette->Entries(3) = ARGB_Green

   ' // Create a SolidBrush
   DIM brush AS CGpSolidBrush = ARGB_BLACK
   
   ' // Display the four palette colors with no adjustment.
   FOR j AS LONG = 0 TO PALETTE_SIZE - 1
      brush.SetColor(clrPalette->Entries(j))
      graphics.FillRectangle(@brush, 30 * j, 0, 20, 20)
   NEXT

   ' // Create a remap table that converts green to blue.
   DIM map AS GpColorMap
   map.oldColor = ARGB_GREEN
   map.newColor = ARGB_VIOLET

   ' // Create an ImageAttributes object, and set its bitmap remap table.
   DIM imgAttr AS CGpImageAttributes
   imgAttr.SetRemapTable(1, @map, ColorAdjustTypeBitmap)

   ' // Adjust the palette.
   imgAttr.GetAdjustedPalette(clrPalette, ColorAdjustTypeBitmap)

   ' // Display the four palette colors after the adjustment.
   FOR j AS LONG = 0 TO PALETTE_SIZE - 1
      brush.SetColor(clrPalette->Entries(j))
      graphics.FillRectangle(@brush, 30 * j, 30, 20, 20)
   NEXT

   ' // Cleanup
   IF clrPalette THEN Deallocate(clrPalette)

END SUB
' ========================================================================================

Reset (CGpImageAttributes)

Clears all color- and grayscale-adjustment settings for a specified category.

FUNCTION Reset (BYVAL nType AS ColorAdjustType = ColorAdjustTypeDefault) AS GpStatus

Return value

If the function succeeds, it returns StatusOk, which is an element of the GpStatus enumeration.

If the function fails, it returns one of the other elements of the GpStatus enumeration.

Remarks

An ImageAttributes object maintains color and grayscale settings for five adjustment categories: default, bitmap, brush, pen, and text. For example, you can specify a gamma value for the default category, a different gamma value for the bitmap category, and still a different gamma value for the pen category.

The default color- and grayscale-adjustment settings apply to all categories that don’t have adjustment settings of their own. For example, if you never specify any adjustment settings for the pen category, then the default settings apply to the pen category.

As soon as you specify a color- or grayscale-adjustment setting for a certain category, the default adjustment settings no longer apply to that category. You can reinstate the default settings for that category by calling Reset. For example, suppose you specify a gamma value for the default category. If you set the gamma value for the pen category by calling SetGamma, then the default gamma value will not apply to pens. If you later pass ColorAdjustTypePen to the Reset method, the pen category will revert to the default gamma value.

Flat API function: GdipResetImageAttributes.

Example

' ========================================================================================
' This example sets a color remap table, draws an adjusted image, resets the attributes,
' and then draws the original image again to show the effect of Reset.
' ========================================================================================
SUB Example_Reset (BYVAL hdc AS HDC)

   ' // Create a graphics object from the window device context
   DIM graphics AS CGpGraphics = hdc
   ' // Set the scaling factors using the DPI ratios
   graphics.ScaleTransformForDpi

   DIM image AS CGpBitmap = "RedGreenStripes.bmp"
   image.SetResolutionForDpi

   ' // Get the width and height of the image
   DIM nWidth AS UINT = image.GetWidth
   DIM nHeight AS UINT = image.GetHeight

   ' // Create an ImageAttributes object
   DIM imgAttr AS CGpImageAttributes

   ' // Create a remap table that converts red to blue.
   DIM map AS GpColorMap
   map.oldColor = ARGB_RED
   map.newColor = ARGB_BLUE
   imgAttr.SetRemapTable(1, @map)

   ' // Draw the image with remap applied
   DIM rc AS GpRect = (10, 10, nWidth, nHeight)
   graphics.DrawImage(@image, @rc, 0, 0, nWidth, nHeight, UnitPixel, @imgAttr)

   ' // Reset the ImageAttributes for the default category
   imgAttr.Reset

   ' // Draw image again (should appear unaltered)
   rc = TYPE<GpRect>(120, 10, nWidth, nHeight)
   graphics.DrawImage(@image, @rc, 0, 0, nWidth, nHeight, UnitPixel, @imgAttr)

END SUB
' ========================================================================================

SetBrushRemapTable (CGpImageAttributes)

Sets the color remap table for the brush category.

FUNCTION SetBrushRemapTable (BYVAL mapSize AS UINT, BYVAL map AS ANY PTR) AS GpStatus

Return value

If the function succeeds, it returns StatusOk, which is an element of the GpStatus enumeration.

If the function fails, it returns one of the other elements of the GpStatus enumeration.

Remarks

A color-remap table is an array of ColorMap structures. Each ColorMap structure has two colors: one that specifies an old color and one that specifies a corresponding new color. During rendering, any color that matches one of the old colors in the remap table is changed to the corresponding new color.

Calling the SetBrushRemapTable method has the same effect as passing ColorAdjustTypeBrush to the SetRemapTable. The specified remap table applies to items in metafiles that are filled with a brush.

Flat API function: GdipSetImageAttributesRemapTable.

SetColorKey (CGpImageAttributes)

Sets the color key (transparency range) for a specified category.

FUNCTION SetColorKey (BYVAL colorLow AS ARGB, BYVAL colorHigh AS ARGB, _
   BYVAL nType AS ColorAdjustType = ColorAdjustTypeDefault) AS GpStatus

Return value

If the function succeeds, it returns StatusOk, which is an element of the GpStatus enumeration.

If the function fails, it returns one of the other elements of the GpStatus enumeration.

Remarks

This method sets the high and low color-key values so that arange of colors can be made transparent. Any color that has each of its three components (red, green, blue) between the corresponding components of the high and low color keys is made transparent.

An ImageAttributes object maintains color and grayscale settings for five adjustment categories: default, bitmap, brush, pen, and text. For example, you can specify a color key for the default category, a different color key for the bitmap category, and still a different color key for the pen category.

The default color- and grayscale-adjustment settings apply to all categories that don’t have adjustment settings of their own. For example, if you never specify any adjustment settings for the pen category, then the default settings apply to the pen category.

As soon as you specify a color- or grayscale-adjustment setting for a certain category, the default adjustment settings no longer apply to that category. For example, suppose you specify a collection of adjustment settings for the default category. If you set the color key for the pen category by passing ColorAdjustTypePen to the SetColorKey method, then none of the default adjustment settings will apply to pens.

Flat API function: GdipSetImageAttributesColorKeys.

Example

' ========================================================================================
' This example sets a color key to make green pixels transparent, then draws the image
' with and without the transparency effect.
' ========================================================================================
SUB Example_SetColorKey (BYVAL hdc AS HDC)

   ' // Create a graphics object from the window device context
   DIM graphics AS CGpGraphics = hdc
   ' // Set the scaling factors using the DPI ratios
   graphics.ScaleTransformForDpi

   ' // Create an Image object based on a .bmp file.
   ' // The image has one stripe with RGB components (160, 0, 0)
   ' // and one stripe with RGB components (0, 140, 0).
   DIM image AS CGpBitmap = "RedGreenStripes.bmp"
   image.SetResolutionForDpi

   ' // Get the width and height of the image
   DIM nWidth AS UINT = image.GetWidth
   DIM nHeight AS UINT = image.GetHeight

   ' // Create an ImageAttributes object, and set its bitmap threshold to 0.6.
   DIM imgAttr AS CGpImageAttributes

   ' // Set color key: make green transparent
   imgAttr.SetColorKey(GDIP_ARGB(255,0,128,0), GDIP_ARGB(255,0,255,0))

   ' // Draw original image (no transparency)
   graphics.DrawImage(@image, 10, 10, nWidth, nHeight)

   ' // Draw image with transparency applied
   DIM rc AS GpRect = (120, 10, nWidth, nHeight)
   graphics.DrawImage(@image, @rc, 0, 0, nWidth, nHeight, UnitPixel, @imgAttr)

END SUB
' ========================================================================================

SetColorMatrices (CGpImageAttributes)

Sets the color-adjustment matrix and the grayscale-adjustment matrix for a specified category.

FUNCTION SetColorMatrices (BYVAL pColorMatrix AS ColorMatrix PTR, _
   BYVAL pGrayMatrix AS ColorMatrix PTR, _
   BYVAL nMode AS ColorAdjustType = ColorMatrixFlagsDefault, _
   BYVAL nType AS LONG = ColorAdjustTypeDefault) AS GpStatus

Return value

If the function succeeds, it returns StatusOk, which is an element of the GpStatus enumeration.

If the function fails, it returns one of the other elements of the GpStatus enumeration.

Remarks

An ImageAttributes object maintains color and grayscale settings for five adjustment categories: default, bitmap, brush, pen, and text. For example, you can specify adjustment matrices for the default category, different adjustment matrices for the bitmap category, and still different adjustment matrices for the pen category.

The default color- and grayscale-adjustment settings apply to all categories that don’t have adjustment settings of their own. For example, if you never specify any adjustment settings for the pen category, then the default settings apply to the pen category.

As soon as you specify a color- or grayscale-adjustment setting for a certain category, the default adjustment settings no longer apply to that category. For example, suppose you specify a collection of adjustment settings for the default category. If you set the color-adjustment and grayscale-adjustment matrices for the pen category by passing ColorAdjustTypePen to the SetColorMatrices method, then none of the default adjustment settings will apply to pens.

Flat API function: GdipSetImageAttributesColorMatrix.

Example

' ========================================================================================
' This example sets the color-adjustment matrix and the grayscale-adjustment matrix for a specified category.
' SetColorMatrices lets you apply both a primary color matrix and a grayscale matrix in one call.
' If you only want one effect, you can pass NULL for the second matrix.
' This is ideal for layered effects like sepia + desaturation, or tint + gamma correction.
' ========================================================================================
SUB Example_SetColorMatrices (BYVAL hdc AS HDC)

   ' // Create a graphics object from the window device context
   DIM graphics AS CGpGraphics = hdc
   ' // Set the scaling factors using the DPI ratios
   graphics.ScaleTransformForDpi

   ' // Create an Image object based on a .bmp file.
   ' // The image has one stripe with RGB components (160, 0, 0)
   ' // and one stripe with RGB components (0, 140, 0).
   DIM image AS CGpBitmap = "climber.jpg"
   image.SetResolutionForDpi

   ' // Get the width and height of the image
   DIM nWidth AS UINT = image.GetWidth
   DIM nHeight AS UINT = image.GetHeight

   ' // Create an ImageAttributes object, and set its bitmap threshold to 0.6.
   DIM imgAttr AS CGpImageAttributes

   ' Define sepia color matrix
   DIM sepiaMatrix AS ColorMatrix
   sepiaMatrix.m(0,0) = 0.393 : sepiaMatrix.m(0,1) = 0.349 : sepiaMatrix.m(0,2) = 0.272
   sepiaMatrix.m(1,0) = 0.769 : sepiaMatrix.m(1,1) = 0.686 : sepiaMatrix.m(1,2) = 0.534
   sepiaMatrix.m(2,0) = 0.189 : sepiaMatrix.m(2,1) = 0.168 : sepiaMatrix.m(2,2) = 0.131
   sepiaMatrix.m(3,3) = 1
   sepiaMatrix.m(4,4) = 1

   ' Define grayscale matrix (optional, for layering)
   DIM grayMatrix AS ColorMatrix
   grayMatrix.m(0,0) = 0.3 : grayMatrix.m(0,1) = 0.3 : grayMatrix.m(0,2) = 0.3
   grayMatrix.m(1,0) = 0.59: grayMatrix.m(1,1) = 0.59: grayMatrix.m(1,2) = 0.59
   grayMatrix.m(2,0) = 0.11: grayMatrix.m(2,1) = 0.11: grayMatrix.m(2,2) = 0.11
   grayMatrix.m(3,3) = 1
   grayMatrix.m(4,4) = 1

   ' // Apply the color matrix
   imgAttr.SetColorMatrices(@sepiaMatrix, @grayMatrix)

   ' // Draw original image
   graphics.DrawImage(@image, 10, 10, nWidth, nHeight)

   ' // Draw image with transparency applied
   DIM rc AS GpRect = (200, 10, nWidth, nHeight)
   graphics.DrawImage(@image, @rc, 0, 0, nWidth, nHeight, UnitPixel, @imgAttr)

END SUB
' ========================================================================================

SetColorMatrix (CGpImageAttributes)

Sets the color-adjustment matrix for a specified category.

FUNCTION SetColorMatrix (BYVAL pColorMatrix AS ColorMatrix PTR, _
   BYVAL nMode AS ColorMatrixFlags = ColorMatrixFlagsDefault, _
   BYVAL nType AS ColorAdjustType = ColorAdjustTypeDefault) AS GpStatus

Return value

If the function succeeds, it returns StatusOk, which is an element of the GpStatus enumeration.

If the function fails, it returns one of the other elements of the GpStatus enumeration.

Remarks

An ImageAttributes object maintains color and grayscale settings for five adjustment categories: default, bitmap, brush, pen, and text. For example, you can specify a color-adjustment matrix for the default category, a different color-adjustment matrix for the bitmap category, and still a different color-adjustment matrix for the pen category.

The default color- and grayscale-adjustment settings apply to all categories that don’t have adjustment settings of their own. For example, if you never specify any adjustment settings for the pen category, then the default settings apply to the pen category.

As soon as you specify a color- or grayscale-adjustment setting for a certain category, the default adjustment settings no longer apply to that category. For example, suppose you specify a collection of adjustment settings for the default category. If you set the color-adjustment matrix for the pen category by passing ColorAdjustTypePen to the SetColorMatrix method, then none of the default adjustment settings will apply to pens.

Flat API function: GdipSetImageAttributesColorMatrix.

Example

' ========================================================================================
' This example applies a grayscale color matrix to an image using SetColorMatrix.
' ========================================================================================
SUB Example_SetColorMatrix (BYVAL hdc AS HDC)

   ' // Create a graphics object from the window device context
   DIM graphics AS CGpGraphics = hdc
   ' // Set the scaling factors using the DPI ratios
   graphics.ScaleTransformForDpi

   ' // Create an Image object based on a .bmp file.
   ' // The image has one stripe with RGB components (160, 0, 0)
   ' // and one stripe with RGB components (0, 140, 0).
   DIM image AS CGpBitmap = "climber.jpg"
   image.SetResolutionForDpi

   ' // Get the width and height of the image
   DIM nWidth AS UINT = image.GetWidth
   DIM nHeight AS UINT = image.GetHeight

   ' // Create an ImageAttributes object, and set its bitmap threshold to 0.6.
   DIM imgAttr AS CGpImageAttributes

   ' // Define grayscale color matrix
   DIM grayMatrix AS ColorMatrix
   grayMatrix.m(0, 0) = 0.3 : grayMatrix.m(0, 1) = 0.3 : grayMatrix.m(0, 2) = 0.3 : grayMatrix.m(0, 3) = 0 : grayMatrix.m(0, 4) = 0
   grayMatrix.m(1, 0) = 0.59: grayMatrix.m(1, 1) = 0.59: grayMatrix.m(1, 2) = 0.59: grayMatrix.m(1, 3) = 0 : grayMatrix.m(1, 4) = 0
   grayMatrix.m(2, 0) = 0.11: grayMatrix.m(2, 1) = 0.11: grayMatrix.m(2, 2) = 0.11: grayMatrix.m(2, 3) = 0 : grayMatrix.m(2, 4) = 0
   grayMatrix.m(3, 0) = 0   : grayMatrix.m(3, 1) = 0   : grayMatrix.m(3, 2) = 0   : grayMatrix.m(3, 3) = 1 : grayMatrix.m(3, 4) = 0
   grayMatrix.m(4, 0) = 0   : grayMatrix.m(4, 1) = 0   : grayMatrix.m(4, 2) = 0   : grayMatrix.m(4, 3) = 0 : grayMatrix.m(4, 4) = 1

   ' // Apply the color matrix
   imgAttr.SetColorMatrix(@grayMatrix)

   ' // Draw original image
   graphics.DrawImage(@image, 10, 10, nWidth, nHeight)

   ' // Draw image with transparency applied
   DIM rc AS GpRect = (200, 10, nWidth, nHeight)
   graphics.DrawImage(@image, @rc, 0, 0, nWidth, nHeight, UnitPixel, @imgAttr)

END SUB
' ========================================================================================

SetGamma (CGpImageAttributes)

Sets the gamma value for a specified category.

FUNCTION SetGamma (BYVAL gamma AS SINGLE, BYVAL nType AS ColorAdjustType = ColorAdjustTypeDefault) AS GpStatus

Return value

If the function succeeds, it returns StatusOk, which is an element of the GpStatus enumeration.

If the function fails, it returns one of the other elements of the GpStatus enumeration.

Remarks

An ImageAttributes object maintains color and grayscale settings for five adjustment categories: default, bitmap, brush, pen, and text. For example, you can specify a gamma value for the default category, a different gamma value for the bitmap category, and still a different gamma value for the pen category.

The default color- and grayscale-adjustment settings apply to all categories that don’t have adjustment settings of their own. For example, if you never specify any adjustment settings for the pen category, then the default settings apply to the pen category.

As soon as you specify a color- or grayscale-adjustment setting for a certain category, the default adjustment settings no longer apply to that category. For example, suppose you specify a collection of adjustment settings for the default category. If you set the gamma value for the pen category by passing ColorAdjustTypePen to the SetGamma method, then none of the default adjustment settings will apply to pens.

Flat API function: GdipSetImageAttributesGamma.

Example

' ========================================================================================
' This example applies gamma correction to an image using the SetGamma method.
' ========================================================================================
SUB Example_SetGamma (BYVAL hdc AS HDC)

   ' // Create a graphics object from the window device context
   DIM graphics AS CGpGraphics = hdc
   ' // Set the scaling factors using the DPI ratios
   graphics.ScaleTransformForDpi

   ' // Create an Image object based on a .bmp file.
   ' // The image has one stripe with RGB components (160, 0, 0)
   ' // and one stripe with RGB components (0, 140, 0).
   DIM image AS CGpBitmap = "climber.jpg"
   image.SetResolutionForDpi

   ' // Get the width and height of the image
   DIM nWidth AS UINT = image.GetWidth
   DIM nHeight AS UINT = image.GetHeight

   ' // Draw the image with no color adjustment.
   graphics.DrawImage(@image, 10, 10, nWidth, nHeight)

   ' // Create an ImageAttributes object, and set its bitmap threshold to 0.6.
   DIM imgAttr AS CGpImageAttributes

   ' // Apply gamma correction (e.g., 2.2)
   imgAttr.SetGamma(2.2)

   ' // Draw original image
   graphics.DrawImage(@image, 10, 10, nWidth, nHeight)

   ' // Draw gamma-adjusted image
   DIM rc AS GpRect = (200, 10, nWidth, nHeight)
   graphics.DrawImage(@image, @rc, 0, 0, nWidth, nHeight, UnitPixel, @imgAttr)

END SUB
' ========================================================================================

SetNoOp (CGpImageAttributes)

Turns off color adjustment for a specified category. You can call ClearNoOp to reinstate the color-adjustment settings that were in place before the call to SetNoOp.

FUNCTION SetNoOp (BYVAL nType AS ColorAdjustType = ColorAdjustTypeDefault) AS GpStatus

Return value

If the function succeeds, it returns StatusOk, which is an element of the GpStatus enumeration.

If the function fails, it returns one of the other elements of the GpStatus enumeration.

Flat API function: GdipSetImageAttributesNoOp.

Example

' ========================================================================================
' This example applies a color matrix to convert the image to grayscale, then disables it
' with SetNoOp to display the original image.
' ========================================================================================
SUB Example_SetNoOp (BYVAL hdc AS HDC)

   ' Crear objeto gráfico
   DIM graphics AS CGpGraphics = hdc
   graphics.ScaleTransformForDpi

   ' Cargar imagen
   DIM image AS CGpBitmap = "climber.jpg"
   image.SetResolutionForDpi

   ' Obtener dimensiones
   DIM nWidth AS UINT = image.GetWidth
   DIM nHeight AS UINT = image.GetHeight

   ' Crear ImageAttributes y aplicar matriz de escala de grises
   DIM imgAttr AS CGpImageAttributes
   DIM grayMatrix AS ColorMatrix
   grayMatrix.m(0,0) = 0.3 : grayMatrix.m(0,1) = 0.3 : grayMatrix.m(0,2) = 0.3
   grayMatrix.m(1,0) = 0.59: grayMatrix.m(1,1) = 0.59: grayMatrix.m(1,2) = 0.59
   grayMatrix.m(2,0) = 0.11: grayMatrix.m(2,1) = 0.11: grayMatrix.m(2,2) = 0.11
   grayMatrix.m(3,3) = 1
   grayMatrix.m(4,4) = 1
   imgAttr.SetColorMatrix(@grayMatrix)

   ' Dibujar imagen con escala de grises
   DIM rcGray AS GpRect = (10, 10, nWidth, nHeight)
   graphics.DrawImage(@image, @rcGray, 0, 0, nWidth, nHeight, UnitPixel, @imgAttr)

   ' Desactivar ajustes de color
   imgAttr.SetNoOp

   ' Dibujar imagen original (sin efectos)
   DIM rcOriginal AS GpRect = (210, 10, nWidth, nHeight)
   graphics.DrawImage(@image, @rcOriginal, 0, 0, nWidth, nHeight, UnitPixel, @imgAttr)

END SUB
' ========================================================================================

SetOutputChannel (CGpImageAttributes)

Sets the CMYK output channel for a specified category.

FUNCTION SetOutputChannel (BYVAL channelFlags AS LONG, _
   BYVAL nType AS ColorAdjustType = ColorAdjustTypeDefault) AS GpStatus

Return value

If the function succeeds, it returns StatusOk, which is an element of the GpStatus enumeration.

If the function fails, it returns one of the other elements of the GpStatus enumeration.

Remarks

You can use the SetOutputChannel method to convert an image to a cyan-magenta-yellow-black (CMYK) color space and examine the intensities of one of the CMYK color channels. For example, suppose you create an ImageAttributes object and set its bitmap output channel to ColorChannelFlagsC. If you pass the address of that ImageAttributes object to the DrawImage method, the cyan component of each pixel is calculated, and each pixel in the rendered image is a shade of gray that indicates the intensity of its cyan channel. Similarly, you can render images that indicate the intensities of the magenta, yellow, and black channels.

An ImageAttributes object maintains color and grayscale settings for five adjustment categories: default, bitmap, brush, pen, and text. For example, you can specify an output channel for the default category and a different output channel for the bitmap category.

The default color- and grayscale-adjustment settings apply to all categories that don’t have adjustment settings of their own. For example, if you never specify any adjustment settings for the bitmap category, then the default settings apply to the bitmap category.

As soon as you specify a color- or grayscale-adjustment setting for a certain category, the default adjustment settings no longer apply to that category. For example, suppose you specify a collection of adjustment settings for the default category. If you set the output channel for the bitmap category by passing ColorAdjustTypeBitmap to the SetOutputChannel method, then none of the default adjustment settings will apply to bitmaps.

Flat API function: GdipSetImageAttributesOutputChannel.

Example

' ========================================================================================
' The following example creates an Image object and calls the DrawImage method to draw the
' image. Then the code creates an ImageAttributes object and sets its bitmap output channel
' to cyan (ColorChannelFlagsC). The code calls DrawImage a second time, passing the address
' of the Image object and the address of the ImageAttributes object. The cyan channel of
' each pixel is calculated, and the rendered image shows the intensities of the cyan channel
' as shades of gray. The code calls DrawImage three more times to show the intensities of
' the magenta, yellow, and black channels.
' ========================================================================================
SUB Example_SetOutputChannel (BYVAL hdc AS HDC)

   ' // Create a graphics object from the window device context
   DIM graphics AS CGpGraphics = hdc
   ' // Set the scaling factors using the DPI ratios
   graphics.ScaleTransformForDpi

   ' // Create an Image object based on a .bmp file.
   ' // The image has one stripe with RGB components (160, 0, 0)
   ' // and one stripe with RGB components (0, 140, 0).
   DIM image AS CGpBitmap = "Mosaic2.bmp"
   image.SetResolutionForDpi

   ' // Draw the image unaltered.
   DIM nWidth AS UINT = image.GetWidth
   DIM nHeight AS UINT = image.GetHeight
   graphics.DrawImage(@image, 10, 10, nWidth, nHeight)

   ' // Create an ImageAttributes object, and set its bitmap threshold to 0.6.
   DIM imgAttr AS CGpImageAttributes

   ' // Draw the image, showing the intensity of the cyan channel.
   imgAttr.SetOutputChannel(ColorChannelFlagsC)
   DIM rc AS GpRect = (110, 10, nWidth, nHeight)
   graphics.DrawImage(@image, @rc, 0, 0, nWidth, nHeight, UnitPixel, @imgAttr)

   ' // Draw the image, showing the intensity of the magenta channel.
   imgAttr.SetOutputChannel(ColorChannelFlagsM)
   rc = Type<GpRect>(210, 10, nWidth, nHeight)
   graphics.DrawImage(@image, @rc, 0, 0, nWidth, nHeight, UnitPixel, @imgAttr)
 
    ' // Draw the image, showing the intensity of the yellow channel.
   imgAttr.SetOutputChannel(ColorChannelFlagsY)
   rc = Type<GpRect>(10, 110, nWidth, nHeight)
   graphics.DrawImage(@image, @rc, 0, 0, nWidth, nHeight, UnitPixel, @imgAttr)

    ' // Draw the image, showing the intensity of the black channel.
   imgAttr.SetOutputChannel(ColorChannelFlagsK)
   rc = Type<GpRect>(110, 110, nWidth, nHeight)
   graphics.DrawImage(@image, @rc, 0, 0, nWidth, nHeight, UnitPixel, @imgAttr)

END SUB
' ========================================================================================

SetOutputChannelColorProfile (CGpImageAttributes)

Sets the output channel color-profile file for a specified category.

FUNCTION SetOutputChannelColorProfile (BYVAL pwszColorProfileFilename AS WSTRING PTR, _
   BYVAL nType AS ColorAdjustType = ColorAdjustTypeDefault) AS GpStatus

Return value

If the function succeeds, it returns StatusOk, which is an element of the GpStatus enumeration.

If the function fails, it returns one of the other elements of the GpStatus enumeration.

Remarks

You can use the SetOutputChannel and SetOutputChannelColorProfile methods to convert an image to a cyan-magenta-yellow-black (CMYK) color space and examine the intensities of one of the CMYK color channels. For example, suppose you write code that performs the following steps:

• Create an Image object.
• Create an ImageAttributes object.
• Pass ColorChannelFlagsC to the SetOutputChannel method of the ImageAttributes object.
• Pass the path name of a color profile file to the SetOutputChannelColorProfile method of the ImageAttributes object.
• Pass the addresses of the Image and ImageAttributes objects to the DrawImage method.

Windows GDI+ will use the color-profile file to calculate the cyan component of each pixel in the image, and each pixel in the rendered image will be a shade of gray that indicates the intensity of its cyan channel.

An ImageAttributes object maintains color and grayscale settings for five adjustment categories: default, bitmap, brush, pen, and text. For example, you can specify an output channel color-profile file for the default category and a different output channel color-profile file for the bitmap category.

The default color- and grayscale-adjustment settings apply to all categories that don’t have adjustment settings of their own. For example, if you never specify any adjustment settings for the bitmap category, then the default settings apply to the bitmap category.

As soon as you specify a color- or grayscale-adjustment setting for a certain category, the default adjustment settings no longer apply to that category. For example, suppose you specify a collection of adjustment settings for the default category. If you set the output channel color-profile file for the bitmap category by passing ColorAdjustTypeBitmap to the SetOutputChannelColorProfile method, then none of the default adjustment settings will apply to bitmaps.

Flat API function: GdipSetImageAttributesOutputChannelColorProfile.

Example

' ========================================================================================
' This example sets a CMYK output channel color profile using SetOutputChannelColorProfile.
' ========================================================================================
SUB Example_SetOutputChannelColorProfile (BYVAL hdc AS HDC)

   ' // Create a graphics object from the window device context
   DIM graphics AS CGpGraphics = hdc
   ' // Set the scaling factors using the DPI ratios
   graphics.ScaleTransformForDpi

   ' // Create an Image object based on a .bmp file.
   ' // The image has one stripe with RGB components (160, 0, 0)
   ' // and one stripe with RGB components (0, 140, 0).
   DIM image AS CGpBitmap = "climber.jpg"
   image.SetResolutionForDpi

   ' // Draw the image unaltered.
   DIM nWidth AS UINT = image.GetWidth
   DIM nHeight AS UINT = image.GetHeight
   graphics.DrawImage(@image, 10, 10, nWidth, nHeight)

   ' // Create an ImageAttributes object, and set its bitmap threshold to 0.6.
   DIM imgAttr AS CGpImageAttributes

   ' // Set CMYK color profile (must be a valid ICC file path)
   DIM colorProfileFilename AS WSTRING * MAX_PATH = "C:\Program Files\Bullzip\PDF Printer\icc\sRGB_IEC61966-2-1_no_black_scaling.icc"
   imgAttr.SetOutputChannelColorProfile(colorProfileFilename)

   ' // Draw image with color profile applied
   DIM rc AS GpRect = (10, 10, nWidth, nHeight)
   graphics.DrawImage(@image, @rc, 0, 0, nWidth, nHeight, UnitPixel, @imgAttr)

END SUB
' ========================================================================================

SetRemapTable (CGpImageAttributes)

Sets the color-remap table for a specified category.

FUNCTION SetRemapTable (BYVAL mapSize AS UINT, BYVAL map AS ANY PTR, _
   BYVAL nType AS ColorAdjustType = ColorAdjustTypeDefault) AS GpStatus

Return value

If the function succeeds, it returns StatusOk, which is an element of the GpStatus enumeration.

If the function fails, it returns one of the other elements of the GpStatus enumeration.

Remarks

A color-remap table is an array of ColorMap structures. Each ColorMap structure has two colors: one that specifies an old color and one that specifies a corresponding new color. During rendering, any color that matches one of the old colors in the remap table is changed to the corresponding new color.

An ImageAttributes object maintains color and grayscale settings for five adjustment categories: default, bitmap, brush, pen, and text. For example, you can specify a color remap for the default category, a color-remap table for the bitmap category, and still a different color-remap table for the pen category.

The default color- and grayscale-adjustment settings apply to all categories that don’t have adjustment settings of their own. For example, if you never specify any adjustment settings for the pen category, then the default settings apply to the pen category.

As soon as you specify a color- or grayscale-adjustment setting for a certain category, the default adjustment settings no longer apply to that category. For example, suppose you specify a collection of adjustment settings for the default category. If you set the color-remap table for the pen category by passing ColorAdjustTypePen to the SetRemapTable method, then none of the default adjustment settings will apply to pens.

Flat API function: GdipSetImageAttributesRemapTable.

Examples

' ========================================================================================
' The following example creates an Image object based on a .bmp file and then draws the image.
' The code creates an ImageAttributes object and sets its default remap table so that red
' is converted to blue. Then the code draws the image again using the color adjustment
' specified by the remap table.
' ========================================================================================
SUB Example_SetRemapTable (BYVAL hdc AS HDC)

   ' // Create a graphics object from the window device context
   DIM graphics AS CGpGraphics = hdc
   ' // Set the scaling factors using the DPI ratios
   graphics.ScaleTransformForDpi

   DIM image AS CGpBitmap = "RedGreenStripes.bmp"
   image.SetResolutionForDpi

   ' // Create a remap table that converts red to blue.
   DIM map AS GpColorMap
   map.oldColor = ARGB_RED
   map.newColor = ARGB_BLUE

   ' // Create an ImageAttributes object, and set its bitmap remap table.
   DIM imgAttr AS CGpImageAttributes
   imgAttr.SetRemapTable(1, @map, ColorAdjustTypeBitmap)

   ' // Get the width and height of the image
   DIM nWidth AS UINT = image.GetWidth
   DIM nHeight AS UINT = image.GetHeight
   
   ' // Draw the image with no color adjustment
   graphics.DrawImage(@image, 10, 10, nWidth, nHeight)

   ' // Draw the image with red converted to blue.
   DIM rc AS GpRect = (100, 10, nWidth, nHeight)
   graphics.DrawImage(@image, @rc, 0, 0, nWidth, nHeight, UnitPixel, @imgAttr)

END SUB
' ========================================================================================

SetThreshold (CGpImageAttributes)

Sets the threshold (transparency range) for a specified category.

FUNCTION SetThreshold (BYVAL threshold AS SINGLE, _
   BYVAL nType AS ColorAdjustType = ColorAdjustTypeDefault) AS GpStatus

Return value

If the function succeeds, it returns StatusOk, which is an element of the GpStatus enumeration.

If the function fails, it returns one of the other elements of the GpStatus enumeration.

Remarks

The threshold is a value from 0 through 1 that specifies a cutoff point for each color component. For example, suppose the threshold is set to 0.7, and suppose you are rendering a color whose red, green, and blue components are 230, 50, and 220. The red component, 230, is greater than 0.7×255, so the red component will be changed to 255 (full intensity). The green component, 50, is less than 0.7×255, so the green component will be changed to 0. The blue component, 220, is greater than 0.7×255, so the blue component will be changed to 255.

An ImageAttributes object maintains color and grayscale settings for five adjustment categories: default, bitmap, brush, pen, and text. For example, you can specify a threshold for the default category, a threshold for the bitmap category, and still a different threshold for the pen category.

The default color- and grayscale-adjustment settings apply to all categories that don’t have adjustment settings of their own. For example, if you never specify any adjustment settings for the pen category, then the default settings apply to the pen category.

As soon as you specify a color- or grayscale-adjustment setting for a certain category, the default adjustment settings no longer apply to that category. For example, suppose you specify a collection of adjustment settings for the default category. If you set the threshold for the pen category by passing ColorAdjustTypePen to the SetThreshold method, then none of the default adjustment settings will apply to pens.

Flat API function: GdipSetImageAttributesThreshold.

Example

' ========================================================================================
' The following example creates an Image object based on a .bmp file. The code also creates
' an ImageAttributes object and sets its bitmap threshold value to 0.6. Then the code draws
' the image twice: once with no color adjustment and once with the adjustment specified by
' the threshold.
' ========================================================================================
SUB Example_SetThreshold (BYVAL hdc AS HDC)

   ' // Create a graphics object from the window device context
   DIM graphics AS CGpGraphics = hdc
   ' // Set the scaling factors using the DPI ratios
   graphics.ScaleTransformForDpi

   ' // Create an Image object based on a .bmp file.
   ' // The image has one stripe with RGB components (160, 0, 0)
   ' // and one stripe with RGB components (0, 140, 0).
   DIM image AS CGpBitmap = "RedGreenThreshold.bmp"
   image.SetResolutionForDpi

   ' // Create an ImageAttributes object, and set its bitmap threshold to 0.6.
   DIM imgAttr AS CGpImageAttributes
   imgAttr.SetThreshold(0.6)

   ' // Get the width and height of the image
   DIM nWidth AS UINT = image.GetWidth
   DIM nHeight AS UINT = image.GetHeight

   ' // Draw the image with no color adjustment.
   graphics.DrawImage(@image, 10, 10, nWidth, nHeight)

   ' // Draw the image with the threshold applied.
   ' // 160 > 0.6 * 255, so the red stripe will be changed to full intensity.
   ' // 140 < 0.6 * 255, so the green stripe will be changed to zero intensity.
   DIM rc AS GpRect = (100, 10, nWidth, nHeight)
   graphics.DrawImage(@image, @rc, 0, 0, nWidth, nHeight, UnitPixel, @imgAttr)

END SUB
' ========================================================================================

SetToIdentity (CGpImageAttributes)

Sets the color-adjustment matrix of a specified category to identity matrix.

FUNCTION SetToIdentity (BYVAL nType AS ColorAdjustType = ColorAdjustTypeDefault) AS GpStatus

Return value

If the function succeeds, it returns StatusOk, which is an element of the GpStatus enumeration.

If the function fails, it returns one of the other elements of the GpStatus enumeration.

Flat API function: GdipSetImageAttributesToIdentity.

Example

' ========================================================================================
' This example applies a grayscale matrix, then resets it using the SetIdentity method.
' ========================================================================================
SUB Example_SetToIdentity (BYVAL hdc AS HDC)

   ' // Create a graphics object from the window device context
   DIM graphics AS CGpGraphics = hdc
   ' // Set the scaling factors using the DPI ratios
   graphics.ScaleTransformForDpi

   DIM image AS CGpBitmap = "climber.jpg"
   image.SetResolutionForDpi

   ' // Get the width and height of the image
   DIM nWidth AS UINT = image.GetWidth
   DIM nHeight AS UINT = image.GetHeight

   ' // Create an ImageAttributes object
   DIM imgAttr AS CGpImageAttributes

   ' // Define grayscale matrix
   DIM grayMatrix AS ColorMatrix
   grayMatrix.m(0, 0) = 0.3 : grayMatrix.m(0, 1) = 0.3 : grayMatrix.m(0, 2) = 0.3 : grayMatrix.m(0, 3) = 0 : grayMatrix.m(0, 4) = 0
   grayMatrix.m(1, 0) = 0.59: grayMatrix.m(1, 1) = 0.59: grayMatrix.m(1, 2) = 0.59: grayMatrix.m(1, 3) = 0 : grayMatrix.m(1, 4) = 0
   grayMatrix.m(2, 0) = 0.11: grayMatrix.m(2, 1) = 0.11: grayMatrix.m(2, 2) = 0.11: grayMatrix.m(2, 3) = 0 : grayMatrix.m(2, 4) = 0
   grayMatrix.m(3, 0) = 0   : grayMatrix.m(3, 1) = 0   : grayMatrix.m(3, 2) = 0   : grayMatrix.m(3, 3) = 1 : grayMatrix.m(3, 4) = 0
   grayMatrix.m(4, 0) = 0   : grayMatrix.m(4, 1) = 0   : grayMatrix.m(4, 2) = 0   : grayMatrix.m(4, 3) = 0 : grayMatrix.m(4, 4) = 1

   ' // Apply grayscale matrix
   imgAttr.SetColorMatrix(@grayMatrix)

   ' // Draw grayscale image
   DIM rc AS GpRect = (10, 10, nWidth, nHeight)
   graphics.DrawImage(@image, @rc, 0, 0, nWidth, nHeight, UnitPixel, @imgAttr)

   ' // Reset to identity matrix (remove grayscale)
   imgAttr.SetToIdentity

   ' // Draw original image (no color adjustment)
   rc = TYPE<GpRect>(200, 10, nWidth, nHeight)
   graphics.DrawImage(@image, @rc, 0, 0, nWidth, nHeight, UnitPixel, @imgAttr)

END SUB
' ========================================================================================

Example

' ========================================================================================
' This example applies a sepia matrix, then resets it using the SetIdentity method.
' ========================================================================================
SUB Example_SetToIdentity (BYVAL hdc AS HDC)

   ' // Create a graphics object from the window device context
   DIM graphics AS CGpGraphics = hdc
   ' // Set the scaling factors using the DPI ratios
   graphics.ScaleTransformForDpi

   DIM image AS CGpBitmap = "climber.jpg"
   image.SetResolutionForDpi

   ' // Get the width and height of the image
   DIM nWidth AS UINT = image.GetWidth
   DIM nHeight AS UINT = image.GetHeight

   ' // Create an ImageAttributes object
   DIM imgAttr AS CGpImageAttributes

   ' // Define inverted color matrix
   DIM sepiaMatrix AS ColorMatrix
   sepiaMatrix.m(0, 0) = 0.393 : sepiaMatrix.m(0, 1) = 0.349 : sepiaMatrix.m(0, 2) = 0.272 : sepiaMatrix.m(0, 3) = 0 : sepiaMatrix.m(0, 4) = 0
   sepiaMatrix.m(1, 0) = 0.769 : sepiaMatrix.m(1, 1) = 0.686 : sepiaMatrix.m(1, 2) = 0.534 : sepiaMatrix.m(1, 3) = 0 : sepiaMatrix.m(1, 4) = 0
   sepiaMatrix.m(2, 0) = 0.189 : sepiaMatrix.m(2, 1) = 0.168 : sepiaMatrix.m(2, 2) = 0.131 : sepiaMatrix.m(2, 3) = 0 : sepiaMatrix.m(2, 4) = 0
   sepiaMatrix.m(3, 0) = 0     : sepiaMatrix.m(3, 1) =  0    : sepiaMatrix.m(3, 2) =  0    : sepiaMatrix.m(3, 3) = 1 : sepiaMatrix.m(3, 4) = 0
   sepiaMatrix.m(4, 0) = 0     : sepiaMatrix.m(4, 1) =  0    : sepiaMatrix.m(4, 2) =  0    : sepiaMatrix.m(4, 3) = 0 : sepiaMatrix.m(4, 4) = 1

   ' // Apply matrix
   imgAttr.SetColorMatrix(@sepiaMatrix)

   ' // Draw image
   DIM rc AS GpRect = (10, 10, nWidth, nHeight)
   graphics.DrawImage(@image, @rc, 0, 0, nWidth, nHeight, UnitPixel, @imgAttr)

   ' // Reset to identity matrix (remove inverted color matrix)
   imgAttr.SetToIdentity

   ' // Draw original image (no color adjustment)
   rc = TYPE<GpRect>(200, 10, nWidth, nHeight)
   graphics.DrawImage(@image, @rc, 0, 0, nWidth, nHeight, UnitPixel, @imgAttr)

END SUB
' ========================================================================================

SetWrapMode (CGpImageAttributes)

Sets the wrap mode and color used to decide how to tile a texture across a shape, or at shape boundaries. A texture is tiled across a shape to fill it in when the texture is smaller than the shape it is filling.

FUNCTION SetWrapMode (BYVAL nWrap AS WrapMode, BYVAL colour AS ARGB = &HFF000000, _
   BYVAL clamp AS BOOL = FALSE) AS GpStatus

Return value

If the function succeeds, it returns StatusOk, which is an element of the GpStatus enumeration.

If the function fails, it returns one of the other elements of the GpStatus enumeration.

Flat API function: GdipSetImageAttributesWrapMode.

Example

' ========================================================================================
' The following example creates an Image object loading an image from file, creates an
' ImageAttributes object, sets the wrap mode to WrapModeTile and draws the specified
' source rectangle to the destination rectangle, which is four times as large as the
' image itself.
' ========================================================================================
SUB Example_SetWrapMode (BYVAL hdc AS HDC)

   ' // Create a graphics object from the window device context
   DIM graphics AS CGpGraphics = hdc
   ' // Set the scaling factors using the DPI ratios
   graphics.ScaleTransformForDpi

   DIM image AS CGpBitmap = "climber.jpg"
   image.SetResolutionForDpi

   ' // Get the width and height of the image
   DIM nWidth AS UINT = image.GetWidth
   DIM nHeight AS UINT = image.GetHeight

   ' // Create an ImageAttributes object
   DIM imgAttr AS CGpImageAttributes

   ' // Set the wrap mode to WrapModeTile
   imgAttr.SetWrapMode(WrapModeTile, ARGB_BLUE)

   ' // Draw the image
   DIM rcf AS GpRectF = (10, 10, nWidth, nHeight)
   graphics.DrawImage(@image, @rcf, 0, 0, 2 * nWidth, 2 * nHeight, UnitPixel, @imgAttr)

END SUB
' ========================================================================================